From ac2b689cdb36e4f642016c5c04ec6429d46c437d Mon Sep 17 00:00:00 2001 From: Will Jones Date: Wed, 29 Jul 2026 13:59:23 -0700 Subject: [PATCH] docs(python): render index/embeddings/remote/rerankers from __all__ Four packages are now rendered by a single mkdocstrings directive each, driven by the module's `__all__`, instead of a hand-maintained list of symbols. These were where most of the drift was: 7 of 12 rerankers and 14 of 17 embedding functions had never been listed. `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 describing how the reference page is wired up and how to check a docs build locally, plus a step in the "adding a new method on Table" checklist. Co-Authored-By: Claude Opus 5 (1M context) --- AGENTS.md | 29 +++++ docs/src/python/python.md | 127 +++---------------- python/python/lancedb/embeddings/__init__.py | 29 +++++ python/python/lancedb/index.py | 3 + python/python/lancedb/remote/__init__.py | 3 + python/python/lancedb/rerankers/__init__.py | 3 + 6 files changed, 86 insertions(+), 108 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 14ec35441..21631a2cd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -92,6 +92,8 @@ Python bindings changes: * Should use `LOOP.run()` to call the corresponding `AsyncTable` method. 6. Add concrete sync method to `RemoteTable` class in `python/python/lancedb/remote/table.py`. 7. Add unit test in `python/tests/test_table.py`. +8. If you added a new public class or module-level function (not just a method on an + existing class), expose it in the API reference. See "Python API reference" below. TypeScript bindings changes: @@ -103,6 +105,33 @@ TypeScript bindings changes: 5. Add test in `nodejs/__test__/table.test.ts`. 6. Run `npm run docs` to generate TypeScript documentation. +## Python API reference + +`docs/src/python/python.md` is the entire Python API reference. It is maintained by +hand, and anything not listed there is not rendered at all, so new public classes and +module-level functions have to be added explicitly. How depends on the module: + +* `lancedb.index`, `lancedb.embeddings`, `lancedb.remote`, and `lancedb.rerankers` are + rendered by a single directive each, driven by the module's `__all__`. Add the new + name to `__all__` and it appears; forget, and it is silently omitted. +* Everything else (`lancedb`, `lancedb.table`, `lancedb.query`, `lancedb.db`, ...) is + listed symbol by symbol. Add a `::: lancedb..` line to the matching + section, and remember that the page separates synchronous and asynchronous APIs. + +Deliberately undocumented: concrete implementations reached through an abstract base +(`LanceTable`, `LanceDBConnection`, `RemoteDBConnection`), query base classes already +covered by `inherited_members`, and internal helpers. + +Cross-references in docstrings use mkdocstrings syntax, `[text][lancedb.table.Table]`. +Plain relative links such as `[Table](Table)` do not resolve. To check your work: + +```shell +pip install -r docs/requirements.txt +cd docs && PYTHONPATH=. mkdocs build +``` + +The docs site only builds on pushes to `main`, so this is not covered by PR CI. + ## Review Guidelines Please consider the following when reviewing code contributions. diff --git a/docs/src/python/python.md b/docs/src/python/python.md index f15c51159..36044d35d 100644 --- a/docs/src/python/python.md +++ b/docs/src/python/python.md @@ -107,67 +107,17 @@ and combined with [BooleanQuery][lancedb.query.BooleanQuery]. ## Embeddings -::: lancedb.embeddings.registry.EmbeddingFunctionRegistry - -::: lancedb.embeddings.registry.get_registry - -::: lancedb.embeddings.registry.register - -::: lancedb.embeddings.base.EmbeddingFunctionConfig - -::: lancedb.embeddings.base.EmbeddingFunction - -::: lancedb.embeddings.base.TextEmbeddingFunction - -::: lancedb.embeddings.sentence_transformers.SentenceTransformerEmbeddings - -::: lancedb.embeddings.openai.OpenAIEmbeddings - -::: lancedb.embeddings.open_clip.OpenClipEmbeddings - -::: lancedb.embeddings.bedrock.BedRockText - -::: lancedb.embeddings.cohere.CohereEmbeddingFunction - -::: lancedb.embeddings.gemini_text.GeminiText - -::: lancedb.embeddings.gte.GteEmbeddings - -::: lancedb.embeddings.instructor.InstructorEmbeddingFunction - -::: lancedb.embeddings.jinaai.JinaEmbeddings - -::: lancedb.embeddings.ollama.OllamaEmbeddings - -::: lancedb.embeddings.transformers.TransformersEmbeddingFunction - -::: lancedb.embeddings.transformers.ColbertEmbeddings - -::: lancedb.embeddings.voyageai.VoyageAIEmbeddingFunction - -::: lancedb.embeddings.watsonx.WatsonxEmbeddings - -::: lancedb.embeddings.colpali.ColPaliEmbeddings - -::: lancedb.embeddings.imagebind.ImageBindEmbeddings - -::: lancedb.embeddings.siglip.SigLipEmbeddings +::: lancedb.embeddings + options: + show_root_heading: false + show_root_toc_entry: false ## Remote configuration -::: lancedb.remote.ClientConfig - -::: lancedb.remote.TimeoutConfig - -::: lancedb.remote.RetryConfig - -::: lancedb.remote.TlsConfig - -::: lancedb.remote.HeaderProvider - -::: lancedb.remote.OAuthConfig - -::: lancedb.remote.OAuthFlowType +::: lancedb.remote + options: + show_root_heading: false + show_root_toc_entry: false ## Context @@ -205,8 +155,6 @@ tokens = list(lancedb.tokenize("acme makes searchable data", custom_stop_words=["acme"])) ``` -::: lancedb.index.FTS - ::: lancedb.tokenize ::: lancedb.FtsToken @@ -266,29 +214,10 @@ instead of being materialized with the rest of the row. ## Reranking -::: lancedb.rerankers.base.Reranker - -::: lancedb.rerankers.linear_combination.LinearCombinationReranker - -::: lancedb.rerankers.cohere.CohereReranker - -::: lancedb.rerankers.colbert.ColbertReranker - -::: lancedb.rerankers.cross_encoder.CrossEncoderReranker - -::: lancedb.rerankers.openai.OpenaiReranker - -::: lancedb.rerankers.jinaai.JinaReranker - -::: lancedb.rerankers.rrf.RRFReranker - -::: lancedb.rerankers.mrr.MRRReranker - -::: lancedb.rerankers.answerdotai.AnswerdotaiRerankers - -::: lancedb.rerankers.voyageai.VoyageAIReranker - -::: lancedb.rerankers.watsonx.WatsonxReranker +::: lancedb.rerankers + options: + show_root_heading: false + show_root_toc_entry: false ## Connections (Asynchronous) @@ -320,31 +249,13 @@ Table hold your actual data as a collection of records / rows. Indices can be created on a table to speed up queries. This section lists the indices that LanceDb supports. -::: lancedb.index.BTree - -::: lancedb.index.Bitmap - -::: lancedb.index.LabelList - -::: lancedb.index.FTS - -::: lancedb.index.IvfPq - -::: lancedb.index.HnswPq - -::: lancedb.index.HnswSq - -::: lancedb.index.IvfFlat - -::: lancedb.index.IvfSq - -::: lancedb.index.IvfRq - -::: lancedb.index.HnswFlat - -::: lancedb.index.Fm - -::: lancedb.index.IndexConfig +::: lancedb.index + options: + show_root_heading: false + show_root_toc_entry: false + # `lang_mapping` is defined in the module rather than imported, so it is + # picked up despite not being in `__all__`. It is an internal lookup table. + filters: ["!^_", "!^lang_mapping$"] ::: lancedb.table.IndexStatistics diff --git a/python/python/lancedb/embeddings/__init__.py b/python/python/lancedb/embeddings/__init__.py index f70aa57b2..4a39b7900 100644 --- a/python/python/lancedb/embeddings/__init__.py +++ b/python/python/lancedb/embeddings/__init__.py @@ -21,3 +21,32 @@ from .watsonx import WatsonxEmbeddings from .voyageai import VoyageAIEmbeddingFunction from .colpali import ColPaliEmbeddings from .siglip import SigLipEmbeddings + +# The API reference renders this package with a single mkdocstrings directive, +# which only picks up names listed here. New embedding functions must be added +# to both the imports above and this list, or they will silently go undocumented. +__all__ = [ + "EmbeddingFunction", + "EmbeddingFunctionConfig", + "TextEmbeddingFunction", + "EmbeddingFunctionRegistry", + "get_registry", + "register", + "SentenceTransformerEmbeddings", + "OpenAIEmbeddings", + "OpenClipEmbeddings", + "BedRockText", + "CohereEmbeddingFunction", + "GeminiText", + "GteEmbeddings", + "InstructorEmbeddingFunction", + "JinaEmbeddings", + "OllamaEmbeddings", + "TransformersEmbeddingFunction", + "ColbertEmbeddings", + "VoyageAIEmbeddingFunction", + "WatsonxEmbeddings", + "ColPaliEmbeddings", + "ImageBindEmbeddings", + "SigLipEmbeddings", +] diff --git a/python/python/lancedb/index.py b/python/python/lancedb/index.py index 5ced0600f..b5facb123 100644 --- a/python/python/lancedb/index.py +++ b/python/python/lancedb/index.py @@ -845,6 +845,9 @@ class IvfRq: accelerator: Optional[str] = None +# The API reference renders this module with a single mkdocstrings directive, +# which only picks up names listed here. New public names must be added to this +# list, or they will silently go undocumented. __all__ = [ "BTree", "IvfPq", diff --git a/python/python/lancedb/remote/__init__.py b/python/python/lancedb/remote/__init__.py index a6ef55eb5..1f255b991 100644 --- a/python/python/lancedb/remote/__init__.py +++ b/python/python/lancedb/remote/__init__.py @@ -11,6 +11,9 @@ from lancedb import __version__ from .header import HeaderProvider from .oauth import OAuthConfig, OAuthFlowType +# The API reference renders this module with a single mkdocstrings directive, +# which only picks up names listed here. New public names must be added to this +# list, or they will silently go undocumented. __all__ = [ "TimeoutConfig", "RetryConfig", diff --git a/python/python/lancedb/rerankers/__init__.py b/python/python/lancedb/rerankers/__init__.py index 86b0ac884..aef2d331e 100644 --- a/python/python/lancedb/rerankers/__init__.py +++ b/python/python/lancedb/rerankers/__init__.py @@ -14,6 +14,9 @@ from .answerdotai import AnswerdotaiRerankers from .voyageai import VoyageAIReranker from .watsonx import WatsonxReranker +# The API reference renders this module with a single mkdocstrings directive, +# which only picks up names listed here. New public names must be added to this +# list, or they will silently go undocumented. __all__ = [ "Reranker", "CrossEncoderReranker",