docs: clean up griffe warnings, add CI workflow, drop suppression hook

Fix the 29 griffe diagnostics that the build was previously silencing
via scripts/mkdocs_hooks.py so that mkdocs build --strict passes on
unmodified source.

Source-level docstring fixes:

* redisvl/extensions/cache/llm/semantic.py: remove stray space in
  filter_expression type annotations; add missing colons in the
  Raises blocks for update / aupdate.
* redisvl/extensions/cache/llm/langcache.py: type the **kwargs
  documentation on update / aupdate.
* redisvl/extensions/message_history/semantic_history.py: fix the
  hanging continuation line in the as_text Args entry.
* redisvl/extensions/router/semantic.py: align Args names with the
  function signatures (route_name, reference_ids, keys) on
  add_route_references / get_route_references / delete_route_references
  and clean up malformed Optional() syntax.
* redisvl/query/query.py: type *fields, drop the bogus self return
  name, add a BaseQuery return annotation on return_fields, and
  rename text_weights to weights in set_text_weights to match the
  signature.
* redisvl/index/index.py: add BaseSearchIndex return annotations to
  from_yaml and from_dict so griffe stops flagging the Returns block.
* redisvl/utils/vectorize/base.py: type the **kwargs documentation
  on embed / embed_many / aembed / aembed_many and add a
  Generator[list, None, None] return annotation on batchify.
* redisvl/utils/vectorize/text/huggingface.py: type the **kwargs
  documentation on __init__.

Build pipeline:

* Drop scripts/mkdocs_hooks.py and the matching hooks: entry from
  mkdocs.yml. mkdocs build --strict now exits 0 with zero griffe
  warnings.
* Add .github/workflows/docs.yml to run mkdocs build --strict on
  every PR that touches docs, mkdocs config, source, or this
  workflow, and on every push to main. Uploads the rendered site as
  a build artifact for review.

Verified locally with mkdocs build --strict (clean) and mypy on the
edited modules (clean).

Author: nkanu17

.github/workflows/docs.yml

@@ -0,0 +1,60 @@
+name: Docs
+
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "AGENTS.md"
+      - "redisvl/**/*.py"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".readthedocs.yaml"
+      - ".github/workflows/docs.yml"
+  push:
+    branches:
+      - main
+
+env:
+  UV_VERSION: "0.7.13"
+
+jobs:
+  build:
+    name: mkdocs build --strict
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: ${{ env.UV_VERSION }}
+          enable-cache: true
+          python-version: "3.11"
+          cache-dependency-glob: |
+            pyproject.toml
+            uv.lock
+
+      - name: Install docs dependencies
+        run: uv sync --frozen --group docs
+
+      - name: Build docs (strict)
+        env:
+          DISABLE_MKDOCS_2_WARNING: "true"
+        run: uv run mkdocs build --strict
+
+      - name: Upload built site
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: site
+          path: site/
+          retention-days: 7

mkdocs.yml

@@ -122,9 +122,6 @@ plugins:
   - redirects:
       redirect_maps: {}
 
-hooks:
-  - scripts/mkdocs_hooks.py
-
 markdown_extensions:
   - abbr
   - admonition

redisvl/extensions/cache/llm/langcache.py

@@ -569,7 +569,7 @@ def update(self, key: str, **kwargs) -> None:
 
         Args:
             key (str): The key of the document to update.
-            **kwargs: Field-value pairs to update.
+            **kwargs (Any): Field-value pairs to update.
 
         Raises:
             NotImplementedError: LangCache does not support entry updates.
@@ -587,7 +587,7 @@ async def aupdate(self, key: str, **kwargs) -> None:
 
         Args:
             key (str): The key of the document to update.
-            **kwargs: Field-value pairs to update.
+            **kwargs (Any): Field-value pairs to update.
 
         Raises:
             NotImplementedError: LangCache does not support entry updates.

redisvl/extensions/cache/llm/semantic.py

@@ -372,7 +372,7 @@ def check(
             return_fields (Optional[List[str]], optional): The fields to include
                 in each returned result. If None, defaults to all available
                 fields in the cached entry.
-            filter_expression (Optional[FilterExpression]) : Optional filter expression
+            filter_expression (Optional[FilterExpression]): Optional filter expression
                 that can be used to filter cache results. Defaults to None and
                 the full cache will be searched.
             distance_threshold (Optional[float]): The threshold for semantic
@@ -463,7 +463,7 @@ async def acheck(
             return_fields (Optional[List[str]], optional): The fields to include
                 in each returned result. If None, defaults to all available
                 fields in the cached entry.
-            filter_expression (Optional[FilterExpression]) : Optional filter expression
+            filter_expression (Optional[FilterExpression]): Optional filter expression
                 that can be used to filter cache results. Defaults to None and
                 the full cache will be searched.
             distance_threshold (Optional[float]): The threshold for semantic
@@ -704,8 +704,8 @@ def update(self, key: str, **kwargs) -> None:
             key (str): the key of the document to update using kwargs.
 
         Raises:
-            ValueError if an incorrect mapping is provided as a kwarg.
-            TypeError if metadata is provided and not of type dict.
+            ValueError: if an incorrect mapping is provided as a kwarg.
+            TypeError: if metadata is provided and not of type dict.
 
         .. code-block:: python
 
@@ -745,8 +745,8 @@ async def aupdate(self, key: str, **kwargs) -> None:
             key (str): the key of the document to update using kwargs.
 
         Raises:
-            ValueError if an incorrect mapping is provided as a kwarg.
-            TypeError if metadata is provided and not of type dict.
+            ValueError: if an incorrect mapping is provided as a kwarg.
+            TypeError: if metadata is provided and not of type dict.
 
         .. code-block:: python
 

redisvl/extensions/message_history/semantic_history.py

@@ -202,7 +202,7 @@ def get_relevant(
         Args:
             prompt (str): The message text to search for in message history
             as_text (bool): Whether to return the prompts and responses as text
-            or as JSON.
+                or as JSON.
             top_k (int): The number of previous messages to return. Default is 5.
             session_tag (Optional[str]): Tag of the entries linked to a specific
                 conversation session. Defaults to instance ULID.

redisvl/extensions/router/semantic.py

@@ -710,7 +710,7 @@ def add_route_references(
         """Add a reference(s) to an existing route.
 
         Args:
-            router_name (str): The name of the router.
+            route_name (str): The name of the route.
             references (Union[str, List[str]]): The reference or list of references to add.
 
         Returns:
@@ -774,8 +774,9 @@ def get_route_references(
         """Get references for an existing route route.
 
         Args:
-            router_name (str): The name of the router.
-            references (Union[str, List[str]]): The reference or list of references to add.
+            route_name (str): The name of the route.
+            reference_ids (List[str]): The list of reference ids to fetch.
+            keys (List[str]): The list of fully qualified keys to fetch.
 
         Returns:
             List[Dict[str, Any]]]: Reference objects stored
@@ -810,9 +811,9 @@ def delete_route_references(
         """Get references for an existing semantic router route.
 
         Args:
-            router_name Optional(str): The name of the router.
-            reference_ids Optional(List[str]]): The reference or list of references to delete.
-            keys Optional(List[str]]): List of fully qualified keys (prefix:router:reference_id) to delete.
+            route_name (Optional[str]): The name of the route.
+            reference_ids (Optional[List[str]]): The reference or list of references to delete.
+            keys (Optional[List[str]]): List of fully qualified keys (prefix:router:reference_id) to delete.
 
         Returns:
             int: Number of objects deleted

redisvl/index/index.py

@@ -337,14 +337,14 @@ def storage_type(self) -> StorageType:
         return self.schema.index.storage_type
 
     @classmethod
-    def from_yaml(cls, schema_path: str, **kwargs):
+    def from_yaml(cls, schema_path: str, **kwargs) -> "BaseSearchIndex":
         """Create a SearchIndex from a YAML schema file.
 
         Args:
             schema_path (str): Path to the YAML schema file.
 
         Returns:
-            SearchIndex: A RedisVL SearchIndex object.
+            A RedisVL SearchIndex object.
 
         .. code-block:: python
 
@@ -356,14 +356,14 @@ def from_yaml(cls, schema_path: str, **kwargs):
         return cls(schema=schema, **kwargs)
 
     @classmethod
-    def from_dict(cls, schema_dict: dict[str, Any], **kwargs):
+    def from_dict(cls, schema_dict: dict[str, Any], **kwargs) -> "BaseSearchIndex":
         """Create a SearchIndex from a dictionary.
 
         Args:
             schema_dict (Dict[str, Any]): A dictionary containing the schema.
 
         Returns:
-            SearchIndex: A RedisVL SearchIndex object.
+            A RedisVL SearchIndex object.
 
         .. code-block:: python
 

redisvl/query/query.py

@@ -256,17 +256,19 @@ def _query_string(self, value: str | None):
         """Setter for _query_string to maintain compatibility with parent class."""
         self._built_query_string = value
 
-    def return_fields(self, *fields, skip_decode: str | list[str] | None = None):
+    def return_fields(
+        self, *fields, skip_decode: str | list[str] | None = None
+    ) -> "BaseQuery":
         """
         Set the fields to return with search results.
 
         Args:
-            *fields: Variable number of field names to return.
+            *fields (str): Variable number of field names to return.
             skip_decode: Optional field name or list of field names that should not be
                 decoded. Useful for binary data like embeddings.
 
         Returns:
-            self: Returns the query object for method chaining.
+            The query object for method chaining.
 
         Raises:
             TypeError: If skip_decode is not a string, list, or None.
@@ -1593,7 +1595,7 @@ def set_text_weights(self, weights: dict[str, float]):
         """Set or update the text weights for the query.
 
         Args:
-            text_weights: Dictionary of word:weight mappings
+            weights: Dictionary of word:weight mappings
         """
         self._text_weights = self._parse_text_weights(weights)
         self._built_query_string = None

redisvl/utils/vectorize/base.py

@@ -2,7 +2,7 @@
 import logging
 from enum import Enum
 from pathlib import Path
-from typing import Annotated, Any, Callable
+from typing import Annotated, Any, Callable, Generator
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
@@ -85,7 +85,7 @@ def embed(
             preprocess: Function to apply to the content before embedding
             as_buffer: Return the embedding as a binary buffer instead of a list
             skip_cache: Bypass the cache for this request
-            **kwargs: Additional model-specific parameters
+            **kwargs (Any): Additional model-specific parameters
 
         Returns:
             The vector embedding as either a list of floats or binary buffer
@@ -155,7 +155,7 @@ def embed_many(
             batch_size: Number of items to process in each API call
             as_buffer: Return embeddings as binary buffers instead of lists
             skip_cache: Bypass the cache for this request
-            **kwargs: Additional model-specific parameters
+            **kwargs (Any): Additional model-specific parameters
 
         Returns:
             List of vector embeddings in the same order as the inputs
@@ -215,7 +215,7 @@ async def aembed(
             preprocess: Function to apply to the content before embedding
             as_buffer: Return the embedding as a binary buffer instead of a list
             skip_cache: Bypass the cache for this request
-            **kwargs: Additional model-specific parameters
+            **kwargs (Any): Additional model-specific parameters
 
         Returns:
             The vector embedding as either a list of floats or binary buffer
@@ -288,7 +288,7 @@ async def aembed_many(
             batch_size: Number of texts to process in each API call
             as_buffer: Return embeddings as binary buffers instead of lists
             skip_cache: Bypass the cache for this request
-            **kwargs: Additional model-specific parameters
+            **kwargs (Any): Additional model-specific parameters
 
         Returns:
             List of vector embeddings in the same order as the inputs
@@ -532,7 +532,9 @@ async def _astore_in_cache_batch(
                 f"Error storing batch in embedding cache asynchronously: {str(e)}"
             )
 
-    def batchify(self, seq: list, size: int, preprocess: Callable | None = None):
+    def batchify(
+        self, seq: list, size: int, preprocess: Callable | None = None
+    ) -> Generator[list, None, None]:
         """Split a sequence into batches of specified size.
 
         Args:
@@ -541,7 +543,7 @@ def batchify(self, seq: list, size: int, preprocess: Callable | None = None):
             preprocess: Optional function to preprocess each item
 
         Yields:
-            Batches of the sequence
+            Batches of the sequence.
         """
         for pos in range(0, len(seq), size):
             if preprocess is not None:

redisvl/utils/vectorize/text/huggingface.py

@@ -89,7 +89,7 @@ def __init__(
                 Defaults to 'float32'.
             cache (Optional[EmbeddingsCache]): Optional EmbeddingsCache instance to cache embeddings for
                 better performance with repeated texts. Defaults to None.
-            **kwargs: Additional parameters to pass to the SentenceTransformer
+            **kwargs (Any): Additional parameters to pass to the SentenceTransformer
                 constructor.
 
         Raises: