ci: deploy docs to GitHub Pages on push to main (#29)

* docs: deploy to GitHub Pages on push to main

Wires up automated docs publishing now that the source tree is on
MkDocs Material. Build runs on every push to `main` and uploads the
`site/` directory as a Pages artifact; the deploy job ships it to
`https://redis-developer.github.io/sql-redis/`.

Workflow (`.github/workflows/docs.yml`):
- Uses the same uv + Python 3.11 toolchain as `test.yml` and `lint.yml`
  for consistency.
- `fetch-depth: 0` so `mkdocs-git-revision-date-localized-plugin` can
  walk full history when computing per-page modification dates.
- Builds with `--strict` so broken links or missing references fail the
  workflow before deploy runs.
- Deploys via `actions/deploy-pages@v4` (no `gh-pages` branch; uses the
  modern Pages "GitHub Actions" source).
- `concurrency: pages` with `cancel-in-progress: false` so concurrent
  pushes do not interrupt an in-flight deploy.

Config:
- `mkdocs.yml`: `site_url` -> `https://redis-developer.github.io/sql-redis/`
  so canonical links and the auto-generated `llms.txt` point at the
  live host.
- `README.md`: replace the "docs site not yet live" callout with a
  direct link to the GitHub Pages URL; update the `llms.txt` bullet to
  the live URL.
- `AGENTS.md`: same URL update in the discoverable-artifacts table and
  the hub-context section.

Pages itself was enabled on the repo with `build_type=workflow` so the
first run of this workflow on `main` is the first publish.

* docs(readme): drop experimental warnings, add centered Redis logo header

- Remove the orange shields.io "Status: Experimental" badge and the
  matching blockquote callout. The Experimental tier note still lives
  in the docs site for context; the README no longer leads with it.
- Replace the plain `# sql-redis` title with a centered hero block
  matching the redisvl README pattern: Redis logo (canonical SVG from
  `redis/redis-vl-python/docs/_static/`) + `<h1>sql-redis</h1>` +
  one-line tagline + a Documentation / GitHub / PyPI link bar.
- Surface the published docs URL prominently right after the hero so
  new readers land on the live site before scrolling.
- Move the local docs preview command (`make docs-serve`) into the
  existing Development section where the other `make` targets live.

* chore: remove redundant docs link

Author: nkanu17

.github/workflows/docs.yml

@@ -0,0 +1,71 @@
+name: Deploy docs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+env:
+  UV_VERSION: "0.7.13"
+  PYTHON_VERSION: "3.11"
+  DISABLE_MKDOCS_2_WARNING: "true"
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build site
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          # Required by mkdocs-git-revision-date-localized-plugin so it can
+          # walk the full history when computing per-page modification dates.
+          fetch-depth: 0
+
+      - name: Install Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: ${{ env.UV_VERSION }}
+          enable-cache: true
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache-dependency-glob: |
+            pyproject.toml
+            uv.lock
+
+      - name: Install docs dependencies
+        run: uv sync --group docs
+
+      - name: Build site (strict)
+        run: uv run mkdocs build --strict
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

AGENTS.md

@@ -96,7 +96,7 @@ Full reference, generated from docstrings, is at `docs/api/`.
 
 | Artifact | Purpose |
 |---|---|
-| [`llms.txt`](https://docs.redisvl.com/projects/sql-redis/llms.txt) | Auto-generated flat index of every doc page with one-line summaries. Built by `mkdocs-llmstxt` at deploy time. Good for in-context injection. |
+| [`llms.txt`](https://redis-developer.github.io/sql-redis/llms.txt) | Auto-generated flat index of every doc page with one-line summaries. Built by `mkdocs-llmstxt` at deploy time. Good for in-context injection. |
 | [`docs/api/`](docs/api/) | mkdocstrings reference for every public symbol, generated from Google-style docstrings. Source of truth for method signatures. |
 | [`docs/user_guide/how_to_guides/`](docs/user_guide/how_to_guides/) | Task-oriented recipes (vector search, GEO, dates, async, parameters). |
 | [`docs/concepts/`](docs/concepts/) | Why-style explanation: architecture, parameter substitution, schema-aware translation. |
@@ -105,9 +105,10 @@ Full reference, generated from docstrings, is at `docs/api/`.
 ## Hub context
 
 sql-redis sits in the [Redis AI Hub](https://redis.io/ai-hub/) under the
-*Experimental* tier as "SQL for Redis". Public docs URL:
-[`docs.redisvl.com/projects/sql-redis/`](https://docs.redisvl.com/projects/sql-redis/).
-The hub's docs standards (Diataxis layout, docstring-driven API reference,
-AI-agent affordances) are documented at
+*Experimental* tier as "SQL for Redis". Published docs:
+[`redis-developer.github.io/sql-redis/`](https://redis-developer.github.io/sql-redis/)
+(GitHub Pages, deployed by `.github/workflows/docs.yml` on every push to
+`main`). The hub's docs standards (Diataxis layout, docstring-driven API
+reference, AI-agent affordances) are documented at
 [`HUB_DOCS_STANDARDS.md`](https://github.com/redis/docs/blob/main/HUB_DOCS_STANDARDS.md)
 in the hub repo.

README.md

@@ -1,17 +1,18 @@
-# sql-redis
+<div align="center">
+    <img width="300" src="https://raw.githubusercontent.com/redis/redis-vl-python/main/docs/_static/Redis_Logo_Red_RGB.svg" alt="Redis">
+    <h1>sql-redis</h1>
+    <p><strong>SQL on top of RediSearch and RedisVL indexes</strong></p>
+</div>
 
-[![Status: Experimental](https://img.shields.io/badge/status-experimental-orange)](https://redis.io/ai-hub/)
+<div align="center">
 
-A SQL-to-Redis translator that converts SQL `SELECT` statements into Redis `FT.SEARCH` and `FT.AGGREGATE` commands. Query Redis collections with familiar SQL on top of RediSearch and RedisVL indexes.
+**[Documentation](https://redis-developer.github.io/sql-redis/)** • **[GitHub](https://github.com/redis-developer/sql-redis)** • **[PyPI](https://pypi.org/project/sql-redis/)**
 
-> **Status: Experimental.** sql-redis is in the [Redis AI Hub](https://redis.io/ai-hub/) under the Experimental tier. The API can change between minor releases. Not yet production-ready; we are validating the design and the SQL surface in real use.
+</div>
 
-A Diataxis-aligned documentation site (concepts, how-to guides, API reference, examples) lives in [`docs/`](docs/) and will be published at **docs.redisvl.com/projects/sql-redis/** once the hub site is live. Until then, this README is the canonical reference. Build the site locally with:
+---
 
-```bash
-uv sync --group docs
-make docs-serve   # http://localhost:8000
-```
+A SQL-to-Redis translator that converts SQL `SELECT` statements into Redis `FT.SEARCH` and `FT.AGGREGATE` commands. Query Redis collections with familiar SQL on top of RediSearch and RedisVL indexes.
 
 ## Install
 
@@ -428,7 +429,7 @@ Each layer has focused unit tests; 100% coverage is achievable because responsib
 ## For AI agents
 
 - **[`AGENTS.md`](AGENTS.md):** how to use sql-redis from an agent, including gotchas and the error model.
-- **`llms.txt`:** auto-generated at docs-build time (`make docs-build` → `site/llms.txt`). A flat index of every doc page with one-line summaries; it will live at `docs.redisvl.com/projects/sql-redis/llms.txt` once published.
+- **[`llms.txt`](https://redis-developer.github.io/sql-redis/llms.txt):** auto-generated flat index of every doc page with one-line summaries (built by `mkdocs-llmstxt`).
 - **[`docs/for-ais-only/`](docs/for-ais-only/):** repository map, build and test guide, and intentional failure modes for agents modifying the library.
 
 ## Development
@@ -438,6 +439,7 @@ make install       # uv sync --all-extras
 make test          # requires Docker for testcontainers
 make test-cov      # with coverage report
 make lint          # format + mypy
+make docs-serve    # uv sync --group docs && preview at http://localhost:8000
 ```
 
 ## Testing philosophy

mkdocs.yml

@@ -1,6 +1,6 @@
 site_name: sql-redis
 site_description: SQL to Redis FT.SEARCH and FT.AGGREGATE translator.
-site_url: https://docs.redisvl.com/projects/sql-redis/
+site_url: https://redis-developer.github.io/sql-redis/
 repo_url: https://github.com/redis-developer/sql-redis
 repo_name: redis-developer/sql-redis
 edit_uri: edit/main/docs/