docs: migrate from Sphinx to mkdocs material

[nkanu17]

Summary

Migrate the documentation pipeline from Sphinx to mkdocs material so the
public site renders with the same visual language used by sql-redis,
loads faster, and exposes a cleaner Python API surface generated by
mkdocstrings + griffe.

What changed

Documentation toolchain

• Drop the entire docs/_extension/, docs/_static/, docs/_templates/,
  docs/conf.py, docs/Makefile, docs/make.bat Sphinx tree and every
  .rst source file.
• Add mkdocs.yml plus a Material-themed site under docs/ rooted at
  docs/index.md with the Redis Vector Library hero, navigation tree,
  branded color palette (Redis red, Space Grotesk / Space Mono), and a
  full mkdocstrings-driven API reference under docs/api/.
• Convert the architecture, queries, search-and-indexing, extensions,
  field-attributes, mcp, and utilities concept pages from Sphinx-flavored
  myst to plain Markdown.
• Wire the existing user-guide notebooks (docs/user_guide/*.ipynb) into
  the site via mkdocs-jupyter and add docs/user_guide/index.md plus an
  installation page.
• Add machine-readable agent docs under docs/for-ais-only/ (repository
  map, build/test, public API surface, codebase tour) and a top-level
  AGENTS.md entry point. The site emits llms.txt / llms-full.txt
  via mkdocs-llmstxt.
• Custom branding lives in docs/stylesheets/redis-brand.css plus
  docs/assets/ (favicon, hero logo in Redis red, architecture
  diagram).

Build pipeline

• Replace the Sphinx block in .readthedocs.yaml with a mkdocs: block
  and switch the build to uv sync --frozen --group docs.
• Update Makefile so make docs-build and make docs-serve invoke
  mkdocs instead of sphinx-build / sphinx-autobuild.
• Add a new [dependency-groups].docs block in pyproject.toml
  pinning mkdocs, mkdocs-material, mkdocs-jupyter,
  mkdocs-autorefs, mkdocs-llmstxt, mkdocs-redirects,
  mkdocs-section-index, mkdocs-git-revision-date-localized-plugin,
  and mkdocstrings[python]. Lockfile refreshed.
• Ignore the generated site/ output via .gitignore.

CI

• New .github/workflows/docs.yml runs mkdocs build --strict on every
  PR that touches docs/, mkdocs.yml, redisvl/**/*.py, pyproject.toml,
  uv.lock, .readthedocs.yaml, or the workflow itself, and on every
  push to main. The job uploads the rendered site as an artifact so
  reviewers can inspect rendered output.

Source docstring cleanup

Fix the 29 griffe diagnostics that were previously suppressed by a
custom hook so the build passes strict mode without any
warning-silencing scaffolding:

• redisvl/extensions/cache/llm/semantic.py: tighten
  filter_expression annotations and add missing colons in Raises:
  on 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.
• 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__.

With those fixes in place, scripts/mkdocs_hooks.py and the
matching hooks: line in mkdocs.yml are removed.

Verification

• uv sync --frozen --group docs
• DISABLE_MKDOCS_2_WARNING=true uv run mkdocs build --strict exits 0
  with zero griffe warnings.
• uv run mkdocs serve renders the hero, navigation, API reference,
  and embedded notebooks correctly.
• uv run mypy redisvl/index/index.py redisvl/query/query.py redisvl/utils/vectorize/base.py
  is clean after the new return annotations.

Follow-ups (out of scope here)

• Trigger the first ReadTheDocs build of main once this lands and
  confirm docs.redisvl.com (CNAME → redisvl.readthedocs.io)
  publishes the new site.

---

Note

Medium Risk
Moderate risk because it replaces the entire docs build toolchain (MkDocs config, RTD/CI workflow, dependency groups), which could break publishing or strict builds, but it does not change runtime library behavior.

Overview
Migrates the documentation system from Sphinx/MyST + .rst API pages to MkDocs Material with mkdocstrings-generated API reference pages and mkdocs-jupyter notebook rendering, including a new mkdocs.yml nav/site configuration and Redis-branded styling/assets.

Updates docs build automation to match the new toolchain: adds a GitHub Actions Docs workflow that runs mkdocs build --strict, switches .readthedocs.yaml and root Makefile docs targets to MkDocs, and replaces Sphinx-specific docs files (Sphinx config, templates/extensions/static assets, .rst pages) with MkDocs markdown equivalents and new agent-focused docs (AGENTS.md, docs/for-ais-only/).

Adjusts .gitignore for MkDocs cache and updates the docs dependency group in pyproject.toml accordingly, with a few docstring/type-hint tweaks in redisvl to improve generated API docs.

^{Reviewed by Cursor Bugbot for commit 16254c6. Bugbot is set up for automated code reviews on this repo. Configure here.}

[jit-ci]

🛡️ Jit Security Scan Results

✅ No security findings were detected in this PR

---

^{Security scan by Jit}

[Copilot]

Pull request overview

This PR migrates the project documentation toolchain from Sphinx to MkDocs Material to align RedisVL docs with the broader Redis docs ecosystem (theme/branding, mkdocstrings API reference, notebook rendering, and LLM-friendly indexes).

Changes:

• Replaces the Sphinx build system with MkDocs Material (new mkdocs.yml, updated docs deps, updated RTD + Makefile targets).
• Ports docs pages to MkDocs/CommonMark + pymdownx patterns, and converts .rst API pages to mkdocstrings-backed .md.
• Adds AI-agent oriented docs (AGENTS.md and docs/for-ais-only/*) and a docs hook to suppress noisy griffe warnings during strict builds.

Reviewed changes

Copilot reviewed 55 out of 65 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
scripts/mkdocs_hooks.py	Adds MkDocs hook to quiet griffe/mkdocstrings warning-level logging during strict builds.
pyproject.toml	Replaces Sphinx docs dependencies with MkDocs/MkDocs Material toolchain dependencies.
mkdocs.yml	New MkDocs site configuration (theme, plugins, nav, hooks, markdown extensions).
Makefile	Switches docs-build/docs-serve targets from Sphinx artifacts to MkDocs commands.
docs/user_guide/use_cases/index.md	Converts Sphinx grid directives to MkDocs Material “cards” layout + adds frontmatter description.
docs/user_guide/installation.md	Removes MyST metadata block and normalizes code fences/typography for MkDocs.
docs/user_guide/index.md	Reworks landing content to MkDocs Material “cards” layout + adds frontmatter description.
docs/user_guide/how_to_guides/mcp.md	Converts links/admonitions to MkDocs style; large content sections removed.
docs/user_guide/how_to_guides/index.md	Converts grid layout to MkDocs “cards” and keeps quick-reference table.
docs/stylesheets/redis-brand.css	Adds Redis-brand CSS overrides and landing hero styling.
docs/Makefile	Removes Sphinx docs Makefile.
docs/make.bat	Removes Sphinx Windows build script.
docs/index.md	Adds branded landing hero and converts site navigation blocks to MkDocs “cards”.
docs/for-ais-only/REPOSITORY_MAP.md	Adds repository map for AI coding agents.
docs/for-ais-only/index.md	Adds “For AI Agents” landing page with navigation cards.
docs/for-ais-only/FAILURE_MODES.md	Adds troubleshooting/failure-mode guide for agents contributing changes.
docs/for-ais-only/BUILD_AND_TEST.md	Adds build/test/docs command reference for agents.
docs/examples/index.md	Converts admonitions; removes Sphinx gallery-grid-driven “Demo Applications” section.
docs/conf.py	Removes Sphinx configuration.
docs/concepts/utilities.md	Updates cross-references from Sphinx {doc} to MkDocs-relative links.
docs/concepts/search-and-indexing.md	Updates cross-references from Sphinx {doc} to MkDocs-relative links.
docs/concepts/queries.md	Converts admonitions to MkDocs style and updates “Learn more” links.
docs/concepts/mcp.md	Updates link to MCP how-to guide (MkDocs-relative link).
docs/concepts/index.md	Converts concept landing to MkDocs “cards” layout + adds frontmatter description.
docs/concepts/field-attributes.md	Updates API reference links from Sphinx {doc} to MkDocs-relative links.
docs/concepts/extensions.md	Converts admonitions and updates links to MkDocs-relative links.
docs/concepts/architecture.md	Updates image embedding from Sphinx directive to Markdown image link.
docs/assets/redisvl-architecture.svg	Adds/relocates architecture diagram into MkDocs assets.
docs/assets/redis-logo-script.svg	Adds white script logo for theme header.
docs/assets/redis-logo-script-red.svg	Adds red script logo for landing hero.
docs/assets/favicon.png	Adds/relocates favicon into MkDocs assets.
docs/api/vectorizer.rst	Removes Sphinx API page for vectorizers.
docs/api/vectorizer.md	Adds mkdocstrings-based vectorizer API reference page.
docs/api/vector.rst	Removes Sphinx API page for Vector.
docs/api/vector.md	Adds mkdocstrings-based Vector API page and intra-API link.
docs/api/searchindex.rst	Removes Sphinx API page for SearchIndex classes.
docs/api/searchindex.md	Adds mkdocstrings-based SearchIndex/AsyncSearchIndex API page.
docs/api/schema.rst	Removes Sphinx API page for schema/field types.
docs/api/schema.md	Adds mkdocstrings-based schema + field types API page and condensed guidance.
docs/api/router.rst	Removes Sphinx router API page.
docs/api/router.md	Adds mkdocstrings-based router API page.
docs/api/reranker.rst	Removes Sphinx reranker API page.
docs/api/reranker.md	Adds mkdocstrings-based reranker API page.
docs/api/query.rst	Removes Sphinx query API page.
docs/api/query.md	Adds mkdocstrings-based query API page with MkDocs admonitions for notes.
docs/api/message_history.rst	Removes Sphinx message history API page.
docs/api/message_history.md	Adds mkdocstrings-based message history API page.
docs/api/index.md	Replaces Sphinx toctree with MkDocs “cards” API landing page.
docs/api/filter.rst	Removes Sphinx filter API page.
docs/api/filter.md	Adds mkdocstrings-based filter API page.
docs/api/cache.rst	Removes Sphinx cache API page.
docs/api/cache.md	Adds mkdocstrings-based cache API page (currently partial coverage).
docs/_templates/layout.html	Removes Sphinx template override (GA tag injection).
docs/_static/site.webmanifest	Removes Sphinx static manifest.
docs/_static/Redis_Logo_Red_RGB.svg	Removes Sphinx static Redis logo asset.
docs/_static/gallery.yaml	Removes Sphinx gallery data source.
docs/_static/css/custom.css	Removes Sphinx custom CSS.
docs/_extension/gallery_directive.py	Removes custom Sphinx gallery directive implementation.
AGENTS.md	Adds usage-oriented quick reference for AI agents consuming redisvl.
.readthedocs.yaml	Switches RTD build configuration from Sphinx to MkDocs.
.gitignore	Replaces Sphinx build output ignore with MkDocs cache ignore (needs site/ ignore as well).

Comments suppressed due to low confidence (3)

docs/user_guide/how_to_guides/mcp.md:167

• This guide’s frontmatter/intro says it shows how to use the MCP tools, but the page now stops after the config explanation and no longer documents the search-records / upsert-records tool contracts (args, request/response shapes) or troubleshooting/examples that previously existed. That’s a behavioral/content regression and also contradicts the PR description’s “like-for-like content port”; either restore those sections here or link clearly to the page that now contains them.
  docs/api/cache.md:28
• The page description mentions the embeddings cache and schema classes, but the content only renders SemanticCache, LangCacheSemanticCache, and CacheEntry. EmbeddingsCache and CacheHit (which were part of the prior API reference) are missing, so the API reference is now incomplete/misleading. Add the missing mkdocstrings directives (or adjust the page description/scope).

---
description: Semantic cache, embeddings cache, and LangCache integrations for RedisVL.
---

# Cache

## SemanticCache

::: redisvl.extensions.cache.llm.SemanticCache
    options:
      show_root_heading: true
      inherited_members: true

## LangCacheSemanticCache

::: redisvl.extensions.cache.llm.LangCacheSemanticCache
    options:
      show_root_heading: true
      inherited_members: true

## Cache Schema Classes

### CacheEntry

::: redisvl.extensions.cache.llm.schema.CacheEntry
    options:
      show_root_heading: true

docs/examples/index.md:24

• This migration removes the Sphinx “Demo Applications” gallery (previously generated via the gallery-grid directive + docs/_static/gallery.yaml) without adding an equivalent mkdocs representation. That’s a notable content drop and conflicts with the PR description’s “like-for-like content port”; consider porting the demo-app list to a mkdocs-friendly format (table/list) so the same information remains available.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.