mirror of
https://github.com/lancedb/lancedb.git
synced 2026-10-29 14:56:51 +00:00
docs: clarify how to contribute website documentation
The contributor guide mixes up shared documentation, Enterprise placeholders and the SDK reference. It also describes section merging that the assembler doesn't do. This replaces the overlapping instructions with guidance on where to write, how whole-page replacement works, how to preview changes and how to keep unfinished docs hidden. It explains that source changes enter a saved release edition before they appear on staging, and points SDK contributors to the existing reference guide.
This commit is contained in:
Brendan Clement
+82
-54
@@ -72,42 +72,68 @@ are wrappers around the Rust library.
|
||||
* `node`: **Deprecated** Typescript package source code
|
||||
* `java`: Java package source code
|
||||
* `docs/src`: SDK reference, built with mkdocs
|
||||
* `docs/web`: the open-source pages of [docs.lancedb.com](https://docs.lancedb.com)
|
||||
* `docs/web`: website guides for LanceDB OSS and the APIs used by both OSS and Enterprise
|
||||
* `docs/web-tests`: the tests the documentation's code examples are extracted from
|
||||
|
||||
## Documentation
|
||||
|
||||
The open-source pages of [docs.lancedb.com](https://docs.lancedb.com) live in
|
||||
`docs/web`, so a change to behaviour and the change to the page describing it
|
||||
belong in the same pull request.
|
||||
Update the docs in the same pull request as the behavior they describe. You can
|
||||
merge docs before a feature launches; keep the unfinished material hidden until
|
||||
it is ready for readers.
|
||||
|
||||
Preview them locally — this serves `docs/web` on its own, with no other checkout:
|
||||
### Choose the right place
|
||||
|
||||
- `docs/web/` holds website guides for LanceDB OSS and the APIs used by both
|
||||
OSS and Enterprise.
|
||||
- `docs/src/` holds the SDK reference. See [docs/README.md](docs/README.md) for
|
||||
its build and API-generation instructions.
|
||||
- `docs/web-tests/` and `rust/lancedb/tests/` hold tests used to generate the
|
||||
website's code examples.
|
||||
|
||||
Document SDK APIs here, and explain which operations work in OSS and Enterprise.
|
||||
Put Enterprise-specific deployment and operating instructions in the Enterprise
|
||||
documentation.
|
||||
|
||||
Some pages are placeholders that the website build replaces with an Enterprise
|
||||
page. Changes to a placeholder won't appear on the combined site. Put
|
||||
instructions that both products need on a separate page and link to it.
|
||||
|
||||
### Preview and check your change
|
||||
|
||||
From the repository root:
|
||||
|
||||
```bash
|
||||
npm i -g mint # https://mintlify.com/docs/installation
|
||||
cd docs/web && mint dev
|
||||
npm i -g mint@4.2.888
|
||||
(cd docs/web && mint dev)
|
||||
```
|
||||
|
||||
This previews this checkout, including your uncommitted changes. It doesn't
|
||||
include the other documentation sources or render the availability labels.
|
||||
Use the [combined preview](https://github.com/lancedb/docs#development) when
|
||||
checking Enterprise replacements or links to pages from another source.
|
||||
Staging shows saved release editions, so it won't show a new source change
|
||||
just because that change merged.
|
||||
|
||||
Follow the [style guide](https://github.com/lancedb/docs/blob/main/STYLE.md).
|
||||
[Vale](https://vale.sh) checks wording, names and punctuation using the
|
||||
[bundled LanceDB rules](.github/vale/README.md). Pull requests show suggestions
|
||||
on the lines they change. With Vale 3.24.0 installed, check a page with:
|
||||
on the lines they change. With Vale 3.24.0 installed, check a page locally with:
|
||||
|
||||
```bash
|
||||
vale docs/web/indexing/vector-index.mdx
|
||||
```
|
||||
|
||||
This repository holds a page at every path the site publishes, so the whole
|
||||
navigation resolves locally. Enterprise pages exist here as open-source pages --
|
||||
what the capability is, and what the embedded form does instead. A separate
|
||||
private repository supplies the fuller version of each, which replaces the page
|
||||
at the same path when the published site is assembled.
|
||||
Keep existing `{#anchor}` values when changing headings, so links to those
|
||||
sections keep working. Give new headings stable anchors. For links in rendered
|
||||
components, write the path directly, such as `href="/quickstart"`, and spell out
|
||||
attributes rather than using property spreads. That lets versioned docs keep
|
||||
links inside the selected edition. Code examples aren't subject to this rule.
|
||||
|
||||
Four things to know before editing:
|
||||
### Code examples
|
||||
|
||||
**Code examples are not written into the pages.** They live in real tests under
|
||||
`docs/web-tests/{py,ts,rs}`, `docs/web-tests/blob-v2/{py,ts,rs}`, and
|
||||
`rust/lancedb/tests`, are extracted into `docs/web/snippets/`, and are imported
|
||||
by the pages. Edit the test, then regenerate from the repository root:
|
||||
Edit the test that produces an example, then regenerate its snippet. The
|
||||
sources are `docs/web-tests/{py,ts,rs}`, `docs/web-tests/blob-v2/{py,ts,rs}` and
|
||||
`rust/lancedb/tests`. Run this from the repository root:
|
||||
|
||||
```bash
|
||||
uv run docs/web-tests/mdx_snippets_gen.py \
|
||||
@@ -116,55 +142,57 @@ uv run docs/web-tests/mdx_snippets_gen.py \
|
||||
-s rust/lancedb/tests -o docs/web/snippets
|
||||
```
|
||||
|
||||
Review the diff before committing: a few modules currently regenerate with
|
||||
unrelated changes, so commit only the snippets for the examples you changed.
|
||||
Run the tests for the examples you changed; generating a snippet doesn't run
|
||||
its example. Review the generated diff and commit only the relevant snippets
|
||||
with their tests. Don't assume the PR checks execute every documentation
|
||||
example.
|
||||
|
||||
Run the Python, TypeScript and Rust examples in `docs/web-tests/{py,ts,rs}`
|
||||
locally before submitting the change. These examples are not yet wired into
|
||||
pull-request CI; that integration remains follow-up work.
|
||||
### Say where a feature works
|
||||
|
||||
**Every heading carries an explicit `{#anchor}`.** Those anchors are how the
|
||||
Enterprise pages attach their additions to the right section, so they are
|
||||
assigned once and never regenerated. Leave an existing anchor alone even when
|
||||
you reword the heading above it; only new headings need a new one.
|
||||
|
||||
**A page can declare where it applies.** Its frontmatter says whether LanceDB
|
||||
OSS and LanceDB Enterprise support the feature: use only `available` or
|
||||
`unavailable`, and one sentence that explains its scope. Availability describes
|
||||
product support, not whether a particular deployment has enabled or configured
|
||||
the feature. A supported feature stays `available` when it requires setup, a
|
||||
supported SDK or server version, or has differences between offerings. State
|
||||
those requirements in the summary or the relevant section, including unsupported
|
||||
subfeatures. Do not use `varies`, infer support from an unknown status, or mark an
|
||||
absent capability available. Narrow a page to the capability it actually covers
|
||||
when necessary. For example:
|
||||
Use `availability` in a page's frontmatter to describe the support covered by
|
||||
that page. Each product is either `available` or `unavailable`; use the summary
|
||||
and body for setup requirements, SDK differences and unsupported operations.
|
||||
For example, a page about signing in to Enterprise could declare:
|
||||
|
||||
```yaml
|
||||
availability:
|
||||
oss: unavailable
|
||||
enterprise: available
|
||||
summary: >-
|
||||
Requests to a deployment carry an API key or an OAuth token. Embedded
|
||||
These sign-in instructions apply to LanceDB Enterprise. Embedded
|
||||
LanceDB has no server to sign in to.
|
||||
```
|
||||
|
||||
The assembled site renders this as a label above the page's content and as a
|
||||
sidebar tag when only one offering has the feature. Do not also open the page
|
||||
with a badge of its own, and keep a qualification that only one section needs
|
||||
in that section's text. A `mint dev` preview of `docs/web` alone renders
|
||||
neither the labels nor the tags.
|
||||
Check these claims with the feature owner. Don't use `varies`, treat an API
|
||||
stub as working support, or mark a supported feature unavailable just because
|
||||
it needs configuration. If one label can't describe the whole page accurately,
|
||||
make the page's scope narrower and explain the differences.
|
||||
|
||||
**A feature can be documented before its release.** List a draft page in
|
||||
`docs/web/.mintignore`, keep it out of the navigation in `docs.json`, and do not
|
||||
link to it from published pages. Wrap a draft section in an MDX comment,
|
||||
`{/* ... */}`, whose first line names the release, such as
|
||||
`Draft for the Feature X release.` Keep draft table rows and list items in a
|
||||
comment below the table or list, since a comment between rows or items breaks
|
||||
it. Drafts are hidden from readers but stay in the source, and availability does
|
||||
not change what is published. At release, remove the comments and the
|
||||
`.mintignore` entries, and restore the navigation and links. See
|
||||
Assembly turns this declaration into a page label and, for a feature supported
|
||||
by only one product, a sidebar tag. Don't add those badges by hand. Availability
|
||||
labels do not hide unreleased content.
|
||||
|
||||
### Write docs before launch
|
||||
|
||||
You don't need to hold a documentation PR until launch. Use these controls:
|
||||
|
||||
- For a whole page, add its path to `docs/web/.mintignore`. Leave it out of
|
||||
`docs/web/docs.json`, redirects and links from published pages. Removing a
|
||||
sidebar entry alone doesn't hide a page.
|
||||
- For a section, wrap it in an MDX comment, `{/* ... */}`, with a note such as
|
||||
`Draft for the Feature X release.` Put draft table rows and list items in a
|
||||
comment below the table or list, not between entries.
|
||||
|
||||
Drafts remain in the source. Use them to avoid advertising an unfinished
|
||||
feature, not to keep information confidential. See
|
||||
[Writing docs before release](https://github.com/lancedb/docs#writing-docs-before-release)
|
||||
in the documentation repository's README for previews and release checks.
|
||||
for examples and how to preview a draft.
|
||||
|
||||
Before the intended release, remove the draft controls, restore the navigation
|
||||
and links, and check the result. Those changes must be in the source commit the
|
||||
edition uses. A later change to `main` doesn't update an edition already saved.
|
||||
For a mistake in an existing edition, fix the source and request a
|
||||
[recorded correction](https://github.com/lancedb/docs#correcting-a-saved-edition).
|
||||
|
||||
## Release process
|
||||
|
||||
|
||||
+7
-4
@@ -1,10 +1,13 @@
|
||||
# LanceDB Documentation
|
||||
|
||||
LanceDB docs are available at [docs.lancedb.com](https://docs.lancedb.com).
|
||||
For website guides in `docs/web`, start with
|
||||
[Documentation in CONTRIBUTING.md](../CONTRIBUTING.md#documentation). That
|
||||
covers editing pages, generated examples, previews, availability and drafts.
|
||||
|
||||
The SDK docs are built and deployed automatically by [Github Actions](../.github/workflows/docs.yml)
|
||||
whenever a commit is pushed to the `main` branch. So it is possible for the docs to show
|
||||
unreleased features.
|
||||
This page covers the SDK reference in `docs/src`, built with MkDocs. Its
|
||||
[GitHub Actions workflow](../.github/workflows/docs.yml) builds and deploys on
|
||||
pushes to `main`, so it can include unreleased APIs. That is separate from the
|
||||
release editions of the Mintlify website.
|
||||
|
||||
## Building the docs
|
||||
|
||||
|
||||
Reference in New Issue
Block a user