mirror of
https://github.com/lancedb/lancedb.git
synced 2026-08-18 12:08:35 +00:00
Will Jones
5a1015ba72
`docs/src/python/python.md` is the whole Python API reference, but it is maintained by hand and had drifted from the public API. Anything not listed there simply doesn't get rendered, so a number of public, documented, tested APIs were invisible to users — most notably branch management, where `diff` and `merge` live. I audited every public symbol reachable from `lancedb` and its subpackages against the `:::` directives on the page. This adds the missing ones: - **Branching** — `Branches`, `AsyncBranches` (`list` / `create` / `checkout` / `delete` / `diff` / `merge`) - **Tables** — `TableStatistics` (returned by `Table.stats()`; the fragment-level stats classes were already listed) - **Full text queries** — `FullTextQuery`, `MatchQuery`, `PhraseQuery`, `BoostQuery`, `MultiMatchQuery`, `BooleanQuery`, `FullTextOperator`, `Occur` - **Querying** — `LanceEmptyQueryBuilder`, `LanceTakeQueryBuilder`, `AsyncTakeQuery` - **Indices** — `Fm` (the FM-index for substring search), `IndexConfig` - **Blobs** — `blob`, `BlobType`, `BlobFile` - **Namespaces** — `connect_namespace`, `connect_namespace_async`, and both namespace connection classes - **Remote config** — `TlsConfig`, `HeaderProvider`, `OAuthConfig`, `OAuthFlowType` - **Rerankers** — the `Reranker` base class plus `JinaReranker`, `RRFReranker`, `MRRReranker`, `AnswerdotaiRerankers`, `VoyageAIReranker`, `WatsonxReranker` (5 of 12 were listed) - **Embeddings** — `get_registry`, `register`, and the 14 embedding functions that were missing (3 of 17 were listed) - **PyTorch** — `StreamingDataset` and the permutation API it is built on - **Misc** — `Session`, `tokenize`, `FtsToken`, `pydantic.Vector`, `pydantic.MultiVector`, `instrument_lancedb_metrics`, and the two exception types It also repairs cross-references in docstrings that no longer resolve: links into guide pages that have since moved to lancedb.com (`querying-an-ann-index`, `experimental-full-text-search`), `lance.dataset` references with no inventory behind them, and the relative targets `[Table](Table)` and `[PyArrow Table](pyarrow.Table)`. Deliberately left out: concrete implementation classes reached through their abstract base (`LanceTable`, `LanceDBConnection`, `RemoteDBConnection`), query base classes already covered by `inherited_members: true`, and internal plumbing such as `FullTextSearchQuery` and `ColumnOrdering`. ## Testing The docs job only runs on pushes to `main`, so I built the site locally and compared against a build of `upstream/main`: every added entry resolves, and no symbol that was rendered before stopped being rendered when the four packages moved to automodule. `mkdocs build --strict` exits 0 on this branch, against 61 warnings on `main`. ## Also in this PR `lancedb.index`, `lancedb.embeddings`, `lancedb.remote` and `lancedb.rerankers` are now rendered by a single mkdocstrings directive each, driven by the module's `__all__`, rather than a hand-maintained list. These four are where most of the drift was, and `__all__` is harder to forget than a docs page. `lancedb.embeddings` had no `__all__`; without one mkdocstrings renders no members at all for a re-export package, so one is added. AGENTS.md gains a section on how the page is wired up and how to build the docs locally. Rendering all that code for the first time surfaced ~100 more build warnings, which would have made #3707 (turning on `mkdocs build --strict`) harder to land, so the warning backlog is cleared here too. 97 of the 158 warnings were one systematic false positive — griffe cannot see the generated `__init__` of a pydantic dataclass, so every documented parameter looks unknown — switched off via `warn_unknown_params`. The remaining 61 came from 15 docstrings with real bugs: prose trailing a `Parameters` section (we were rendering parameters called `The`, `you` and `To`), types dropped because numpydoc needs spaces around the colon, `num_partitions, default sqrt(num_rows)` parsing as a list of names and inventing a `default` parameter, and one parameter indented five spaces. `mkdocs build --strict` now exits 0. --- #3747 (the coverage test that keeps this from happening again) is stacked on this branch, so review it after this one. --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
158 lines
4.8 KiB
YAML
158 lines
4.8 KiB
YAML
site_name: LanceDB
|
|
site_url: https://lancedb.github.io/lancedb/
|
|
repo_url: https://github.com/lancedb/lancedb
|
|
edit_uri: https://github.com/lancedb/lancedb/tree/main/docs/src
|
|
repo_name: lancedb/lancedb
|
|
docs_dir: src
|
|
watch:
|
|
- src
|
|
- ../python/python
|
|
|
|
theme:
|
|
name: "material"
|
|
logo: assets/logo.png
|
|
favicon: assets/favicon.ico
|
|
palette:
|
|
# Palette toggle for light mode
|
|
- scheme: lancedb
|
|
primary: custom
|
|
toggle:
|
|
icon: material/weather-night
|
|
name: Switch to dark mode
|
|
# Palette toggle for dark mode
|
|
- scheme: slate
|
|
primary: custom
|
|
toggle:
|
|
icon: material/weather-sunny
|
|
name: Switch to light mode
|
|
features:
|
|
- content.code.copy
|
|
- content.tabs.link
|
|
- content.action.edit
|
|
- content.tooltips
|
|
- toc.follow
|
|
- navigation.top
|
|
- navigation.footer
|
|
- navigation.tracking
|
|
- navigation.instant
|
|
- content.footnote.tooltips
|
|
icon:
|
|
repo: fontawesome/brands/github
|
|
annotation: material/arrow-right-circle
|
|
|
|
plugins:
|
|
- search
|
|
- autorefs
|
|
- mkdocstrings:
|
|
handlers:
|
|
python:
|
|
# Ensure the handler points to the real package root
|
|
# so it reads local sources at python/python/lancedb
|
|
paths: [../python/python]
|
|
options:
|
|
docstring_style: numpy
|
|
docstring_options:
|
|
# Attributes documented in a `Parameters` section, and pydantic
|
|
# dataclasses whose `__init__` griffe cannot see statically, both
|
|
# trip this check. It reports nothing actionable here.
|
|
warn_unknown_params: false
|
|
heading_level: 3
|
|
show_signature_annotations: true
|
|
show_root_heading: true
|
|
show_docstring_examples: true
|
|
show_docstring_attributes: false
|
|
show_docstring_other_parameters: true
|
|
show_symbol_type_heading: true
|
|
show_labels: false
|
|
show_if_no_docstring: true
|
|
show_source: false
|
|
members_order: source
|
|
docstring_section_style: list
|
|
signature_crossrefs: true
|
|
separate_signature: true
|
|
filters:
|
|
- "!^_"
|
|
import:
|
|
# for cross references
|
|
- https://arrow.apache.org/docs/objects.inv
|
|
- https://pandas.pydata.org/docs/objects.inv
|
|
- https://docs.pydantic.dev/latest/objects.inv
|
|
- render_swagger:
|
|
allow_arbitrary_locations: true
|
|
# - redirects:
|
|
# redirect_maps:
|
|
# # Redirect the home page and other top-level markdown files. This enables maximum SEO benefit
|
|
# # other sub-pages are handled by the ingected js in overrides/partials/header.html
|
|
# 'index.md': 'https://lancedb.com/docs/'
|
|
# 'guides/tables.md': 'https://lancedb.com/docs/tables/'
|
|
# 'ann_indexes.md': 'https://lancedb.com/docs/indexing/'
|
|
# 'basic.md': 'https://lancedb.com/docs/quickstart/'
|
|
# 'faq.md': 'https://lancedb.com/docs/faq/'
|
|
# 'embeddings/understanding_embeddings.md': 'https://lancedb.com/docs/embedding/'
|
|
# 'integrations.md': 'https://lancedb.com/docs/integrations/'
|
|
# 'examples.md': 'https://lancedb.com/docs/tutorials/'
|
|
# 'concepts/vector_search.md': 'https://lancedb.com/docs/search/vector-search/'
|
|
# 'troubleshooting.md': 'https://lancedb.com/docs/troubleshooting/'
|
|
# 'guides/storage.md': 'https://lancedb.com/docs/storage/integrations'
|
|
|
|
|
|
|
|
markdown_extensions:
|
|
- admonition
|
|
- footnotes
|
|
- pymdownx.critic
|
|
- pymdownx.caret
|
|
- pymdownx.keys
|
|
- pymdownx.mark
|
|
- pymdownx.tilde
|
|
- pymdownx.details
|
|
- pymdownx.highlight:
|
|
anchor_linenums: true
|
|
line_spans: __span
|
|
pygments_lang_class: true
|
|
- pymdownx.inlinehilite
|
|
- pymdownx.snippets:
|
|
base_path: ..
|
|
dedent_subsections: true
|
|
- pymdownx.superfences
|
|
- pymdownx.tabbed:
|
|
alternate_style: true
|
|
- md_in_html
|
|
- abbr
|
|
- attr_list
|
|
- pymdownx.snippets
|
|
- pymdownx.emoji:
|
|
emoji_index: !!python/name:material.extensions.emoji.twemoji
|
|
emoji_generator: !!python/name:material.extensions.emoji.to_svg
|
|
- markdown.extensions.toc:
|
|
toc_depth: 4
|
|
permalink: true
|
|
permalink_title: Anchor link to this section
|
|
|
|
nav:
|
|
- Documentation:
|
|
- SDK Reference: index.md
|
|
- Python: python/python.md
|
|
- Javascript/TypeScript: js/globals.md
|
|
- Java: java/java.md
|
|
- Rust: https://docs.rs/lancedb/latest/lancedb/index.html
|
|
|
|
extra_css:
|
|
- styles/global.css
|
|
- styles/extra.css
|
|
|
|
extra_javascript:
|
|
- "extra_js/reo.js"
|
|
|
|
extra:
|
|
analytics:
|
|
provider: google
|
|
property: G-B7NFM40W74
|
|
social:
|
|
- icon: fontawesome/brands/github
|
|
link: https://github.com/lancedb/lancedb
|
|
- icon: fontawesome/brands/x-twitter
|
|
link: https://twitter.com/lancedb
|
|
- icon: fontawesome/brands/linkedin
|
|
link: https://www.linkedin.com/company/lancedb
|