rust/lancedb
1
0
Fork 0
mirror of https://github.com/lancedb/lancedb.git synced 2026-10-12 23:02:28 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: describe the documentation workflow in CONTRIBUTING

Browse Source 
The README that carried this sat inside docs/web, which is the published site
root, so it would have shipped as a page. Contributor guidance belongs in the
contributing guide, which is also where someone changing behaviour will look for
whether the page describing it is theirs to update.
This commit is contained in:
Jack Ye
2026-09-02 21:10:35 -07:00
parent b21fb2a4dc
commit e687c64f94
2 changed files with 37 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+37 -1
View File
@@ -71,7 +71,43 @@ are wrappers around the Rust library.
* `nodejs`: Typescript package source code
* `node`: **Deprecated** Typescript package source code
* `java`: Java package source code
* `docs`: Documentation 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-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.
Preview them locally — this serves `docs/web` on its own, with no other checkout:
```bash
npm i -g mint # https://mintlify.com/docs/installation
cd docs/web && mint dev
```
Enterprise pages live in a separate private repository and are merged in when
the published site is assembled, so links to `/enterprise/...` and the SQL and
Geneva sections will not resolve locally. Every open-source page does.
Two things to know before editing:
**Code examples are not written into the pages.** They live in real tests under
`docs/web-tests/{py,ts,rs}`, are extracted into `docs/web/snippets/`, and are
imported by the pages. Edit the test, then regenerate:
```bash
uv run docs/web-tests/mdx_snippets_gen.py -s docs/web-tests/py
```
An example that stops compiling fails the pull request that broke it.
**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.
## Release process
docs/web/README.md
-35
View File
@@ -1,35 +0,0 @@
# LanceDB documentation
The open-source pages of [docs.lancedb.com](https://docs.lancedb.com), beside the
code they describe.
## Preview locally
```bash
npm i -g mint # https://mintlify.com/docs/installation
cd docs/web && mint dev
```
That serves this directory on its own. Enterprise pages live in a private
repository and are merged in when the published site is assembled, so links to
`/enterprise/...` and the SQL and Geneva sections will not resolve here. Every
open-source page does.
## Code examples
Examples are not written into the pages. They live in real tests under
`docs/web-tests/{py,ts,rs}`, are extracted into `docs/web/snippets/`, and are
imported by the pages. Edit the test, then regenerate:
```bash
uv run docs/web-tests/mdx_snippets_gen.py -s docs/web-tests/py
```
An example that does not compile fails the pull request that broke it.
## Section anchors
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 not regenerated — leave an existing one alone even if the
heading it sits on is reworded.