docs: migrate to MkDocs Material, apply Redis branding, restore Diataxis README

[nkanu17]

Summary

Migrates the documentation from Sphinx to MkDocs Material, applies the
official Redis brand (palette, typography, logo, favicon), restores the
comprehensive README content reorganized along the Diataxis tiers, and
wires up automated publishing to GitHub Pages.

After merge, the docs publish automatically to
https://redis-developer.github.io/sql-redis/ on every push to
main.

What changed

Build pipeline

• mkdocs.yml is the new source of truth (replaces docs/conf.py,
  docs/Makefile, and the _static/ / _templates/ Sphinx scaffolding).
• pyproject.toml defines a docs dependency group on
  mkdocs-material, mkdocstrings[python], mkdocs-llmstxt,
  mkdocs-section-index, mkdocs-autorefs, and
  mkdocs-git-revision-date-localized-plugin.
• Makefile exposes make docs-build and make docs-serve.
• .readthedocs.yaml switched to the mkdocs: block; uv installs the
  docs group on RTD (kept as a backup host; primary is GitHub Pages).

Hosting (GitHub Pages)

• New workflow .github/workflows/docs.yml builds the site in --strict
  mode and deploys via actions/deploy-pages@v4. No gh-pages branch.
• Pages enabled on the repo with build_type=workflow. HTTPS enforced.
• mkdocs.yml site_url set to https://redis-developer.github.io/sql-redis/
  so canonical links and llms.txt point at the live host.
• concurrency: pages with cancel-in-progress: false so concurrent
  pushes do not interrupt an in-flight deploy.
• fetch-depth: 0 so mkdocs-git-revision-date-localized-plugin can
  walk full history when computing per-page modification dates.
• Cost: $0 (public repo Pages + Actions minutes are free).

Content (Diataxis)

• docs/concepts/ (Explanation): why-SQL, why-sqlglot, schema-aware
  translation, search-vs-aggregate, async invariants, parameter and
  vector substitution, result shape, testing philosophy, architecture.
• docs/user_guide/ (Tutorial + How-to): getting started plus
  task-oriented recipes for vector search, GEO, dates, async, parameters,
  text search.
• docs/api/ (Reference): one page per public symbol generated from
  Google-style docstrings via mkdocstrings.
• docs/examples/: end-to-end notebooks-as-prose (analytics on
  embeddings, CLI REPL).
• docs/for-ais-only/: internal repo map, build and test guide,
  intentional failure modes.
• llms.txt and llms-full.txt are emitted at build time by
  mkdocs-llmstxt (artifacts under site/, not committed).

Branding

• Material primary and accent point at the Redis red #FF4438 via
  docs/stylesheets/redis-brand.css (overrides --md-primary-fg-color
  and --md-accent-fg-color).
• Body font Space Grotesk, code font Space Mono, matches
  redis-docs/tailwind.config.js.
• Header logo is the cursive redis script wordmark
  (docs/assets/redis-logo-script.svg, white).
• Browser favicon is the Redis 32x32 red mark sourced from the
  redis-vl-python docs (docs/assets/favicon.png).
• Top-level sidebar entries are bold so single-page items match the
  section-header weight produced by navigation.sections.

Independent site

• Removed the Redis AI Hub header injection
  (docs/javascripts/redis-ai-hub-header.js plus the .rah-* CSS).
  The site stands alone; it is no longer wrapped in the hub chrome.

README

• Restored the comprehensive content from before the slim-down (TEXT
  search modes, IS NULL / ismissing, exists(), DATE/DATETIME
  handling, date functions, full GEO catalog, design rationale,
  architecture diagram).
• Reorganized along Diataxis tiers (Tutorial, Reference, How-to,
  Explanation, then practical sections).
• Links straight to the GitHub Pages URL.
• Keeps the recent improvements (pip install, create_executor()
  factory, make install/test/lint, AI Hub status note).

Files of note

• mkdocs.yml, docs/stylesheets/redis-brand.css,
  docs/assets/{favicon.png,redis-logo-script.svg}: site config and
  brand assets.
• .github/workflows/docs.yml: build + deploy on push to main.
• README.md: full Diataxis-aligned restoration; GitHub Pages URL.
• AGENTS.md, docs/for-ais-only/{index.md,BUILD_AND_TEST.md}:
  Sphinx-specific text replaced with MkDocs equivalents; URL updates.

Verification

$ DISABLE_MKDOCS_2_WARNING=true uv run --group docs mkdocs build --strict
INFO    -  Documentation built in ~3s

Local preview:

make docs-serve   # http://localhost:8000

The first publish runs as soon as this PR merges to main; the deploy
URL will appear in the Actions run summary and at
https://redis-developer.github.io/sql-redis/.

Follow-ups (out of scope, optional)

1. Custom domain on Pages (e.g. sql-redis.redis.io) is a one-line
   CNAME change once DNS is set up. Not required.
2. The docs.redisvl.com/projects/sql-redis/ subproject route on RTD
   is no longer needed; .readthedocs.yaml can be deleted in a later
   cleanup PR if we standardize on Pages.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9cd5290294

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Remove unsupported RTD formats for MkDocs builds

Switching this project from sphinx to mkdocs while leaving formats: [pdf, epub] enabled makes the Read the Docs config inconsistent with RTD’s MkDocs support: RTD’s config reference explicitly warns that additional formats (pdf, epub, htmlzip) are not supported for MkDocs projects. This can cause post-merge RTD builds to fail or remain in an error state even if local mkdocs build passes, blocking docs publication.

Useful? React with 👍 / 👎.