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
Medium risk because it replaces the docs toolchain and publishing/CI pipeline (MkDocs + new RTD config + strict build checks), which could break doc builds or navigation despite minimal impact on runtime code.

Overview
Migrates the documentation system from Sphinx/RST to MkDocs Material with a new mkdocs.yml site config, refreshed navigation/landing pages, and mkdocstrings-based API reference pages under docs/api/.

Updates the build/publish pipeline to match: adds a Docs GitHub Action that runs mkdocs build --strict and uploads the rendered site/ artifact, switches ReadTheDocs to MkDocs, and changes make docs-build/make docs-serve to use mkdocs.

Removes Sphinx-only assets/config (docs/conf.py, docs/Makefile, templates/static, .rst files) and adds Redis-branded MkDocs styling/assets plus new agent-focused docs (AGENTS.md, docs/for-ais-only/*), while making small docstring/type-hint tweaks across a few Python modules to satisfy strict mkdocstrings/griffe rendering.

^{Reviewed by Cursor Bugbot for commit fd93955. 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.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit fd93955. Configure here.}

[cursor]

Classmethod return type loses subclass type information

Medium Severity

The new -> "BaseSearchIndex" return annotation on from_yaml and from_dict classmethods is incorrect for inherited classmethods that return cls(...). When called as SearchIndex.from_yaml(...), type checkers will infer the result as BaseSearchIndex, hiding subclass-specific methods like create, query, load, and delete. The codebase already imports Self from typing_extensions in redisvl/query/aggregate.py — that's the correct annotation here. The same issue applies to return_fields returning "BaseQuery" instead of Self, which breaks typed method chaining on subclasses like VectorQuery.

Additional Locations (2)

• redisvl/index/index.py#L358-L359
• redisvl/query/query.py#L260-L261

 

^{Reviewed by Cursor Bugbot for commit fd93955. Configure here.}

[Copilot]

Pull request overview

Copilot reviewed 62 out of 73 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (1)

redisvl/extensions/router/semantic.py:783

• The Returns: line has an extra closing bracket (List[Dict[str, Any]]]: ...). This looks like a typo and can confuse readers/tools parsing the docstring. Remove the extra ] so the return type renders cleanly.

[paoloredis]

@tylerhutcherson have you given any more thought to migrating the docs to redis.io/docs/ entirely?