lancedb/docs

1. This repository is a documentation site, not the product runtime itself. The center of gravity is docs/, which contains Mintlify-authored MDX pages, site configuration, static assets, and generated content for LanceDB topics.

2. The docs are organized by product surface area: quickstart, tables, storage, indexing, search, reranking, embeddings, integrations, enterprise, Geneva, API reference, tutorials, and datasets. These sections map directly to the navigation defined in docs/docs.json.

3. docs/docs.json is the top-level site/navigation boundary. Mintlify uses it to build the sidebar and page structure, while docs/static/ provides images, CSS, and other assets referenced from the pages.

4. A major architectural pattern is “tested code snippets as documentation.” The language-specific example suites in tests/py, tests/ts, and tests/rs are the source of truth for code blocks. scripts/mdx_snippets_gen.py converts those tested snippets into MDX under docs/snippets/, and the Makefile exposes this as make py, make ts, make rs, or make snippets.

5. The snippet pipeline is intentionally one-way: tests validate the examples, then generated MDX is imported into pages via <CodeBlock>-style usage. This keeps docs examples aligned with working Python, TypeScript, and Rust APIs rather than hand-maintained prose snippets.

6. Dataset documentation is another generated subsystem. scripts/sync_hf_datasets.py reads scripts/hf_datasets.yaml, fetches upstream HF_DATASET_CARD.md files from the lance-format/lance-huggingface GitHub repo, rewrites them into Mintlify-compatible MDX, updates docs/datasets/*.mdx, refreshes docs/datasets/index.mdx, and keeps the Datasets sidebar section in sync.

7. The API reference is handled separately under docs/api-reference/, with the REST schema stored in docs/api-reference/rest/openapi.yml. A GitHub Actions workflow (.github/workflows/sync-openapi.yml) keeps that spec synchronized, so the reference docs remain tied to the current API contract.

8. CI and automation live in .github/workflows/. docs-ci.yml is the main documentation validation pipeline, covering site correctness and likely link/content checks. These workflows are the release boundary for changes to docs content and generated artifacts.

9. The repo also contains a dedicated documentation-audit workflow under workflows/docs-audit/. That is a separate Python toolchain with its own config, prompts, manifests, parser, visibility logic, and tests. It appears to run periodic audits of documentation coverage/quality, including enterprise-specific gap detection, and uses OpenAI plus an internal enterprise store abstraction.

10. Tutorials under docs/tutorials/ are a second-order content layer: they mix narrative docs with runnable example code and sometimes companion files like config.py, main.py, and requirements.txt. These are closer to end-to-end recipes than reference pages.

11. The skills/ and workflows/docs-audit/skills/ directories contain authoring guidance for automation and AI-assisted workflows. They are not runtime code paths, but they shape how docs are generated, reviewed, and audited.

12. In architecture-diagram terms, the repository has three main flows: authoring flow from MDX/editable content into Mintlify; generation flow from tests/upstream sources into docs/snippets/ and docs/datasets/; and validation/automation flow through GitHub Actions and the docs-audit toolchain. The boundaries are clear: source content, generated docs, and CI/audit automation.