mirror of
https://github.com/lancedb/lancedb.git
synced 2026-10-13 23:32:27 +00:00
96 lines
2.6 KiB
Markdown
96 lines
2.6 KiB
Markdown
# LanceDB Documentation
|
|
|
|
LanceDB docs are available at [docs.lancedb.com](https://docs.lancedb.com).
|
|
|
|
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.
|
|
|
|
## Building the docs
|
|
|
|
### Setup
|
|
1. Install LanceDB Python. See setup in [Python contributing guide](../python/CONTRIBUTING.md).
|
|
Run `make develop` to install the Python package.
|
|
2. Install documentation dependencies. From LanceDB repo root: `pip install -r docs/requirements.txt`
|
|
|
|
### Preview the docs
|
|
|
|
Run these commands from the LanceDB repository root. The subshell changes into
|
|
`docs` to load `mkdocs.yml`, while leaving your shell in the repository root.
|
|
|
|
```shell
|
|
(cd docs && PYTHONPATH=. mkdocs serve)
|
|
```
|
|
|
|
If you want to just generate the HTML files:
|
|
|
|
```shell
|
|
(cd docs && PYTHONPATH=. mkdocs build)
|
|
```
|
|
|
|
If successful, you should see a `docs/site` directory in the repository root that
|
|
you can verify locally.
|
|
|
|
## Adding examples
|
|
|
|
To make sure examples are correct, we put examples in test files so they can be
|
|
run as part of our test suites.
|
|
|
|
You can see the tests are at:
|
|
|
|
* Python: `python/python/tests/docs`
|
|
* Typescript: `nodejs/examples/`
|
|
|
|
### Checking python examples
|
|
|
|
```shell
|
|
cd python
|
|
pytest -vv python/tests/docs
|
|
```
|
|
|
|
### Checking typescript examples
|
|
|
|
The examples depend on `@lancedb/lancedb` at `file:../dist`, so the package must be
|
|
built before running the tests. This uses pnpm; see the
|
|
[Typescript contributing guide](../nodejs/CONTRIBUTING.md) for the toolchain setup.
|
|
|
|
```shell
|
|
pushd nodejs
|
|
pnpm install
|
|
pnpm build
|
|
popd
|
|
```
|
|
|
|
Then you can run the examples by going to the `nodejs/examples` directory, which is a
|
|
separate pnpm package with its own lockfile:
|
|
|
|
```shell
|
|
pushd nodejs/examples
|
|
pnpm install
|
|
pnpm test
|
|
popd
|
|
```
|
|
|
|
## API documentation
|
|
|
|
### Python
|
|
|
|
The Python API documentation is organized based on the file `docs/src/python/python.md`.
|
|
We manually add entries there so we can control the organization of the reference page.
|
|
**However, this means any new types must be manually added to the file.** No additional
|
|
steps are needed to generate the API documentation.
|
|
|
|
### Typescript
|
|
|
|
The typescript API documentation is generated from the typescript source code using [typedoc](https://typedoc.org/).
|
|
|
|
When new APIs are added, you must manually re-run the typedoc command to update the API documentation.
|
|
The new files should be checked into the repository.
|
|
|
|
```shell
|
|
pushd nodejs
|
|
# `pnpm docs` would invoke pnpm's built-in `docs` command, not the script.
|
|
pnpm run docs
|
|
popd
|
|
```
|