diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4a73f8b35..b7ecc16bb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 diff --git a/docs/README.md b/docs/README.md index c5a99943d..5e434c520 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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