From ed6be12ad6961d10b3c106f9446420c1507eee0b Mon Sep 17 00:00:00 2001 From: Will Jones Date: Wed, 29 Jul 2026 14:15:20 -0700 Subject: [PATCH] docs: clear the mkdocs warning backlog so --strict passes `mkdocs build` emitted 61 warnings on main, and rendering the previously undocumented classes in this PR pushed that to 158. That backlog is what blocks turning on strict mode (#3707), so clear it here rather than leave it worse than we found it. Most of it was one systematic false positive: griffe cannot see the generated `__init__` of a pydantic dataclass, so every documented parameter looked unknown. `warn_unknown_params` turns that check off. The rest were real docstring bugs, in 15 docstrings: * Prose trailing a `Parameters` section is read as parameter names, which invented parameters called `The`, `you` and `To`. Moved into `Notes` or the summary. * numpydoc only reads a type when the colon has spaces around it. Where the documented name is a pydantic attribute rather than a signature parameter, griffe has no signature to fall back on and the type was dropped. Affects nine embedding classes. * `num_partitions, default sqrt(num_rows)` and friends parse as a list of names, rendering a bogus `default` parameter. * One parameter indented five spaces instead of four. `nodejs/CONTRIBUTING.md` links to the repo-root CONTRIBUTING.md, which does not resolve once typedoc copies the file into `docs/src/js/_media/`; an absolute URL works from both places. `mkdocs build --strict` now exits 0. Co-Authored-By: Claude Opus 5 (1M context) --- docs/mkdocs.yml | 5 ++ docs/src/js/_media/CONTRIBUTING.md | 2 +- nodejs/CONTRIBUTING.md | 2 +- python/python/lancedb/embeddings/bedrock.py | 10 ++-- python/python/lancedb/embeddings/cohere.py | 8 ++-- python/python/lancedb/embeddings/colpali.py | 4 +- .../python/lancedb/embeddings/gemini_text.py | 6 +-- python/python/lancedb/embeddings/gte.py | 8 ++-- .../python/lancedb/embeddings/instructor.py | 16 +++---- python/python/lancedb/embeddings/jinaai.py | 4 +- .../embeddings/sentence_transformers.py | 8 ++-- python/python/lancedb/embeddings/voyageai.py | 4 +- python/python/lancedb/index.py | 46 +++++++++---------- python/python/lancedb/table.py | 18 +++++--- 14 files changed, 77 insertions(+), 64 deletions(-) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 324b6fda5..ad6fc4b65 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -51,6 +51,11 @@ plugins: 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 diff --git a/docs/src/js/_media/CONTRIBUTING.md b/docs/src/js/_media/CONTRIBUTING.md index d784b9f75..2faa8cd37 100644 --- a/docs/src/js/_media/CONTRIBUTING.md +++ b/docs/src/js/_media/CONTRIBUTING.md @@ -1,7 +1,7 @@ # Contributing to LanceDB Typescript This document outlines the process for contributing to LanceDB Typescript. -For general contribution guidelines, see [CONTRIBUTING.md](../CONTRIBUTING.md). +For general contribution guidelines, see [CONTRIBUTING.md](https://github.com/lancedb/lancedb/blob/main/CONTRIBUTING.md). ## Project layout diff --git a/nodejs/CONTRIBUTING.md b/nodejs/CONTRIBUTING.md index d784b9f75..2faa8cd37 100644 --- a/nodejs/CONTRIBUTING.md +++ b/nodejs/CONTRIBUTING.md @@ -1,7 +1,7 @@ # Contributing to LanceDB Typescript This document outlines the process for contributing to LanceDB Typescript. -For general contribution guidelines, see [CONTRIBUTING.md](../CONTRIBUTING.md). +For general contribution guidelines, see [CONTRIBUTING.md](https://github.com/lancedb/lancedb/blob/main/CONTRIBUTING.md). ## Project layout diff --git a/python/python/lancedb/embeddings/bedrock.py b/python/python/lancedb/embeddings/bedrock.py index ffa44f0c8..dc2badceb 100644 --- a/python/python/lancedb/embeddings/bedrock.py +++ b/python/python/lancedb/embeddings/bedrock.py @@ -21,20 +21,20 @@ class BedRockText(TextEmbeddingFunction): """ Parameters ---------- - name: str, default "amazon.titan-embed-text-v1" + name : str, default "amazon.titan-embed-text-v1" The model ID of the bedrock model to use. Supported models for are: - amazon.titan-embed-text-v1 - cohere.embed-english-v3 - cohere.embed-multilingual-v3 - region: str, default "us-east-1" + region : str, default "us-east-1" Optional name of the AWS Region in which the service should be called. - profile_name: str, default None + profile_name : str, default None Optional name of the AWS profile to use for calling the Bedrock service. If not specified, the default profile will be used. - assumed_role: str, default None + assumed_role : str, default None Optional ARN of an AWS IAM role to assume for calling the Bedrock service. If not specified, the current active credentials will be used. - role_session_name: str, default "lancedb-embeddings" + role_session_name : str, default "lancedb-embeddings" Optional name of the AWS IAM role session to use for calling the Bedrock service. If not specified, "lancedb-embeddings" name will be used. diff --git a/python/python/lancedb/embeddings/cohere.py b/python/python/lancedb/embeddings/cohere.py index 8769ddaaa..8fc460f9a 100644 --- a/python/python/lancedb/embeddings/cohere.py +++ b/python/python/lancedb/embeddings/cohere.py @@ -22,7 +22,7 @@ class CohereEmbeddingFunction(TextEmbeddingFunction): Parameters ---------- - name: str, default "embed-multilingual-v2.0" + name : str, default "embed-multilingual-v2.0" The name of the model to use. List of acceptable models: * embed-english-v3.0 @@ -33,12 +33,14 @@ class CohereEmbeddingFunction(TextEmbeddingFunction): * embed-english-light-v2.0 * embed-multilingual-v2.0 - source_input_type: str, default "search_document" + source_input_type : str, default "search_document" The input type for the source column in the database - query_input_type: str, default "search_query" + query_input_type : str, default "search_query" The input type for the query column in the database + Notes + ----- Cohere supports following input types: | Input Type | Description | diff --git a/python/python/lancedb/embeddings/colpali.py b/python/python/lancedb/embeddings/colpali.py index 4b614bce3..7232d32ce 100644 --- a/python/python/lancedb/embeddings/colpali.py +++ b/python/python/lancedb/embeddings/colpali.py @@ -44,7 +44,7 @@ class ColPaliEmbeddings(EmbeddingFunction): The token pooling strategy to use, by default "hierarchical". - "hierarchical": Progressively pools tokens to reduce sequence length. - "lambda": A simpler pooling that uses a custom `pooling_func`. - pooling_func: typing.Callable, optional + pooling_func : typing.Callable, optional A function to use for pooling when `pooling_strategy` is "lambda". pool_factor : int Factor to reduce sequence length if token pooling is enabled (default 2). @@ -52,7 +52,7 @@ class ColPaliEmbeddings(EmbeddingFunction): Quantization configuration for the model. (default None, bitsandbytes needed) batch_size : int Batch size for processing inputs (default 2). - offload_folder: str, optional + offload_folder : str, optional Folder to offload model weights if using CPU offloading (default None). This is useful for large models that do not fit in memory. """ diff --git a/python/python/lancedb/embeddings/gemini_text.py b/python/python/lancedb/embeddings/gemini_text.py index 1102e92d1..32f2d4d04 100644 --- a/python/python/lancedb/embeddings/gemini_text.py +++ b/python/python/lancedb/embeddings/gemini_text.py @@ -48,16 +48,16 @@ class GeminiText(TextEmbeddingFunction): Parameters ---------- - name: str, default "gemini-embedding-001" + name : str, default "gemini-embedding-001" The name of the model to use. Supported models include: - "gemini-embedding-001" (768 dimensions) Note: The legacy "models/embedding-001" format is also supported but "gemini-embedding-001" is recommended. - query_task_type: str, default "retrieval_query" + query_task_type : str, default "retrieval_query" Sets the task type for the queries. - source_task_type: str, default "retrieval_document" + source_task_type : str, default "retrieval_document" Sets the task type for ingestion. Examples diff --git a/python/python/lancedb/embeddings/gte.py b/python/python/lancedb/embeddings/gte.py index 4f547a30b..9bad4b54f 100644 --- a/python/python/lancedb/embeddings/gte.py +++ b/python/python/lancedb/embeddings/gte.py @@ -26,13 +26,13 @@ class GteEmbeddings(TextEmbeddingFunction): Parameters ---------- - name: str, default "thenlper/gte-large" + name : str, default "thenlper/gte-large" The name of the model to use. - device: str, default "cpu" + device : str, default "cpu" Sets the device type for the model. - normalize: str, default "True" + normalize : str, default "True" Controls normalize param in encode function for the transformer. - mlx: bool, default False + mlx : bool, default False Controls which model to use. False for gte-large,True for the mlx version. Examples diff --git a/python/python/lancedb/embeddings/instructor.py b/python/python/lancedb/embeddings/instructor.py index a694fd382..675a0139c 100644 --- a/python/python/lancedb/embeddings/instructor.py +++ b/python/python/lancedb/embeddings/instructor.py @@ -35,23 +35,23 @@ class InstructorEmbeddingFunction(TextEmbeddingFunction): Parameters ---------- - name: str + name : str The name of the model to use. Available models are listed at https://github.com/xlang-ai/instructor-embedding#model-list; The default model is hkunlp/instructor-base - batch_size: int, default 32 + batch_size : int, default 32 The batch size to use when generating embeddings - device: str, default "cpu" + device : str, default "cpu" The device to use when generating embeddings - show_progress_bar: bool, default True + show_progress_bar : bool, default True Whether to show a progress bar when generating embeddings - normalize_embeddings: bool, default True + normalize_embeddings : bool, default True Whether to normalize the embeddings - quantize: bool, default False + quantize : bool, default False Whether to quantize the model - source_instruction: str, default "represent the document for retrieval" + source_instruction : str, default "represent the document for retrieval" The instruction for the source column - query_instruction: str, default "represent the document for retrieving the most + query_instruction : str, default "represent the document for retrieving the most similar documents" The instruction for the query diff --git a/python/python/lancedb/embeddings/jinaai.py b/python/python/lancedb/embeddings/jinaai.py index 720e80e85..9656f041f 100644 --- a/python/python/lancedb/embeddings/jinaai.py +++ b/python/python/lancedb/embeddings/jinaai.py @@ -40,10 +40,10 @@ class JinaEmbeddings(EmbeddingFunction): Parameters ---------- - name: str, default "jina-clip-v1". Note that some models support both image + name : str, default "jina-clip-v1". Note that some models support both image and text embeddings and some just text embedding - api_key: str, default None + api_key : str, default None The api key to access Jina API. If you pass None, you can set JINA_API_KEY environment variable diff --git a/python/python/lancedb/embeddings/sentence_transformers.py b/python/python/lancedb/embeddings/sentence_transformers.py index 30d283cf7..8be02e9f7 100644 --- a/python/python/lancedb/embeddings/sentence_transformers.py +++ b/python/python/lancedb/embeddings/sentence_transformers.py @@ -21,13 +21,13 @@ class SentenceTransformerEmbeddings(TextEmbeddingFunction): Parameters ---------- - name: str, default "all-MiniLM-L6-v2" + name : str, default "all-MiniLM-L6-v2" The name of the model to use. - device: str, default "cpu" + device : str, default "cpu" The device to use for the model - normalize: bool, default True + normalize : bool, default True Whether to normalize the embeddings - trust_remote_code: bool, default True + trust_remote_code : bool, default True Whether to trust the remote code """ diff --git a/python/python/lancedb/embeddings/voyageai.py b/python/python/lancedb/embeddings/voyageai.py index 3cf70d332..4a721c998 100644 --- a/python/python/lancedb/embeddings/voyageai.py +++ b/python/python/lancedb/embeddings/voyageai.py @@ -167,7 +167,7 @@ class VoyageAIEmbeddingFunction(EmbeddingFunction): Parameters ---------- - name: str + name : str The name of the model to use. List of acceptable models: * voyage-4 (1024 dims, general-purpose and multilingual retrieval) @@ -185,7 +185,7 @@ class VoyageAIEmbeddingFunction(EmbeddingFunction): * voyage-law-2 * voyage-code-2 - output_dimension: int, optional + output_dimension : int, optional The output dimension for models that support flexible dimensions. Currently only voyage-multimodal-3.5 supports this feature. Valid options: 256, 512, 1024 (default), 2048. diff --git a/python/python/lancedb/index.py b/python/python/lancedb/index.py index b5facb123..aa7846892 100644 --- a/python/python/lancedb/index.py +++ b/python/python/lancedb/index.py @@ -219,7 +219,7 @@ class HnswPq: distance has a range of (-∞, ∞). If the vectors are normalized (i.e. their l2 norm is 1), then dot distance is equivalent to the cosine distance. - num_partitions, default sqrt(num_rows) + num_partitions: int, default sqrt(num_rows) The number of IVF partitions to create. @@ -228,7 +228,7 @@ class HnswPq: will require too much memory. Each partition becomes its own HNSW graph, so setting this value higher reduces the peak memory use of training. - num_sub_vectors, default is vector dimension / 16 + num_sub_vectors: int, default is vector dimension / 16 Number of sub-vectors of PQ. @@ -244,13 +244,13 @@ class HnswPq: If the dimension is not visible by 8 then we use 1 subvector. This is not ideal and will likely result in poor performance. - num_bits: int, default 8 + num_bits: int, default 8 Number of bits to encode each sub-vector. This value controls how much the sub-vectors are compressed. The more bits the more accurate the index but the slower search. Only 4 and 8 are supported. - max_iterations, default 50 + max_iterations: int, default 50 Max iterations to train kmeans. @@ -263,7 +263,7 @@ class HnswPq: those cases it is unlikely that setting this larger will lead to the index converging anyways. - sample_rate, default 256 + sample_rate: int, default 256 The rate used to calculate the number of training vectors for kmeans. @@ -279,14 +279,14 @@ class HnswPq: Increasing this value might improve the quality of the index but in most cases the default should be sufficient. - m, default 20 + m: int, default 20 The number of neighbors to select for each vector in the HNSW graph. This value controls the tradeoff between search speed and accuracy. The higher the value the more accurate the search but the slower it will be. - ef_construction, default 300 + ef_construction: int, default 300 The number of candidates to evaluate during the construction of the HNSW graph. @@ -297,7 +297,7 @@ class HnswPq: This value should be set to a value that is not less than `ef` in the search phase. - target_partition_size, default is 1,048,576 + target_partition_size: int, default is 1,048,576 The target size of each partition. @@ -351,7 +351,7 @@ class HnswSq: distance has a range of (-∞, ∞). If the vectors are normalized (i.e. their l2 norm is 1), then dot distance is equivalent to the cosine distance. - num_partitions, default sqrt(num_rows) + num_partitions: int, default sqrt(num_rows) The number of IVF partitions to create. @@ -360,7 +360,7 @@ class HnswSq: will require too much memory. Each partition becomes its own HNSW graph, so setting this value higher reduces the peak memory use of training. - max_iterations, default 50 + max_iterations: int, default 50 Max iterations to train kmeans. @@ -373,7 +373,7 @@ class HnswSq: In those cases it is unlikely that setting this larger will lead to the index converging anyways. - sample_rate, default 256 + sample_rate: int, default 256 The rate used to calculate the number of training vectors for kmeans. @@ -389,14 +389,14 @@ class HnswSq: Increasing this value might improve the quality of the index but in most cases the default should be sufficient. - m, default 20 + m: int, default 20 The number of neighbors to select for each vector in the HNSW graph. This value controls the tradeoff between search speed and accuracy. The higher the value the more accurate the search but the slower it will be. - ef_construction, default 300 + ef_construction: int, default 300 The number of candidates to evaluate during the construction of the HNSW graph. @@ -407,7 +407,7 @@ class HnswSq: This value should be set to a value that is not less than `ef` in the search phase. - target_partition_size, default is 1,048,576 + target_partition_size: int, default is 1,048,576 The target size of each partition. @@ -460,7 +460,7 @@ class HnswFlat: distance has a range of (-∞, ∞). If the vectors are normalized (i.e. their l2 norm is 1), then dot distance is equivalent to the cosine distance. - num_partitions, default sqrt(num_rows) + num_partitions: int, default sqrt(num_rows) The number of IVF partitions to create. @@ -470,18 +470,18 @@ class HnswFlat: graph, so setting this value higher reduces the peak memory use of training. - max_iterations, default 50 + max_iterations: int, default 50 Max iterations to train kmeans. When training an IVF index we use kmeans to calculate the partitions. This parameter controls how many iterations of kmeans to run. - sample_rate, default 256 + sample_rate: int, default 256 The rate used to calculate the number of training vectors for kmeans. - m, default 20 + m: int, default 20 The number of neighbors to select for each vector in the HNSW graph. @@ -489,7 +489,7 @@ class HnswFlat: The higher the value the more accurate the search but the slower it will be. - ef_construction, default 300 + ef_construction: int, default 300 The number of candidates to evaluate during the construction of the HNSW graph. @@ -501,7 +501,7 @@ class HnswFlat: than 500. This value should be set to a value that is not less than `ef` in the search phase. - target_partition_size, default is 1,048,576 + target_partition_size: int, default is 1,048,576 The target size of each partition. """ @@ -605,7 +605,7 @@ class IvfFlat: The default value is 256. - target_partition_size, default is 8192 + target_partition_size: int, default is 8192 The target size of each partition. @@ -769,7 +769,7 @@ class IvfPq: The default value is 256. - target_partition_size, default is 8192 + target_partition_size: int, default is 8192 The target size of each partition. @@ -830,7 +830,7 @@ class IvfRq: sample_rate: int, default 256 Controls the number of training vectors: sample_rate * num_partitions. - target_partition_size, default is 8192 + target_partition_size: int, default is 8192 Target size of each partition. """ diff --git a/python/python/lancedb/table.py b/python/python/lancedb/table.py index ca65b7a10..a7c48faf4 100644 --- a/python/python/lancedb/table.py +++ b/python/python/lancedb/table.py @@ -1832,6 +1832,8 @@ class Table(ABC): retrain: bool, default False This parameter is no longer used and is deprecated. + Notes + ----- The frequency an application should call optimize is based on the frequency of data modifications. If data is frequently added, deleted, or updated then optimize should be run frequently. A good rule of thumb is to run optimize if @@ -1986,15 +1988,14 @@ class Table(ABC): change permanent you can use the `[Self::restore]` method. Any operation that modifies the table will fail while the table is in a checked - out state. + out state. To return the table to a normal state use + `[Self::checkout_latest]`. Parameters ---------- version: int | str, The version to check out. A version number (`int`) or a tag (`str`) can be provided. - - To return the table to a normal state use `[Self::checkout_latest]` """ @abstractmethod @@ -3813,6 +3814,8 @@ class LanceTable(Table): retrain: bool, default False This parameter is no longer used and is deprecated. + Notes + ----- The frequency an application should call optimize is based on the frequency of data modifications. If data is frequently added, deleted, or updated then optimize should be run frequently. A good rule of thumb is to run optimize if @@ -5774,15 +5777,14 @@ class AsyncTable: change permanent you can use the `[Self::restore]` method. Any operation that modifies the table will fail while the table is in a checked - out state. + out state. To return the table to a normal state use + `[Self::checkout_latest]`. Parameters ---------- version: int | str, The version to check out. A version number (`int`) or a tag (`str`) can be provided. - - To return the table to a normal state use `[Self::checkout_latest]` """ try: await self._inner.checkout(version) @@ -5966,6 +5968,8 @@ class AsyncTable: retrain: bool, default False This parameter is no longer used and is deprecated. + Notes + ----- The frequency an application should call optimize is based on the frequency of data modifications. If data is frequently added, deleted, or updated then optimize should be run frequently. A good rule of thumb is to run optimize if @@ -6346,6 +6350,8 @@ class Branches: dry_run: bool, default False When True, only preview. When False, attempt the merge. + Notes + ----- A rejected merge returns ``status="rejected"`` instead of raising. """ return LOOP.run(self._table.branches.merge(from_branch, dry_run))