mirror of
https://github.com/lancedb/lancedb.git
synced 2026-08-18 12:08:35 +00:00
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) <noreply@anthropic.com>
This commit is contained in:
Will Jones
@@ -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.<module>.<Name>` 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.
|
||||
|
||||
+19
-108
@@ -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
|
||||
|
||||
|
||||
@@ -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",
|
||||
]
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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",
|
||||
|
||||
Reference in New Issue
Block a user