From c9869cefaffbe27fbd723c58dfd317ab5e5e58e0 Mon Sep 17 00:00:00 2001 From: Nitin Kanukolanu Date: Fri, 8 May 2026 18:34:12 -0400 Subject: [PATCH 1/3] 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. --- .github/workflows/docs.yml | 71 ++++++++++++++++++++++++++++++++++++++ AGENTS.md | 11 +++--- README.md | 6 ++-- mkdocs.yml | 2 +- 4 files changed, 82 insertions(+), 8 deletions(-) create mode 100644 .github/workflows/docs.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..de90888 --- /dev/null +++ b/.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 diff --git a/AGENTS.md b/AGENTS.md index e4bebd9..9f2627b 100644 --- a/AGENTS.md +++ b/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. diff --git a/README.md b/README.md index 3ed0e8c..2d59342 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,9 @@ A SQL-to-Redis translator that converts SQL `SELECT` statements into Redis `FT.S > **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. -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: +Full documentation: **** (Diataxis-aligned: concepts, how-to guides, API reference, examples). Built with MkDocs Material from [`docs/`](docs/) and deployed to GitHub Pages on every push to `main`. + +Build the site locally: ```bash uv sync --group docs @@ -428,7 +430,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 diff --git a/mkdocs.yml b/mkdocs.yml index 232e8c4..baec9e7 100644 --- a/mkdocs.yml +++ b/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/ From 520a2903821d03f5d1f0b45883a49618a58a8cef Mon Sep 17 00:00:00 2001 From: Nitin Kanukolanu Date: Fri, 8 May 2026 19:07:05 -0400 Subject: [PATCH 2/3] 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/`) + `

sql-redis

` + 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. --- README.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 2d59342..6cabbfe 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,20 @@ -# sql-redis +
+ Redis +

sql-redis

+

SQL on top of RediSearch and RedisVL indexes

+
-[![Status: Experimental](https://img.shields.io/badge/status-experimental-orange)](https://redis.io/ai-hub/) +
-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. +
-Full documentation: **** (Diataxis-aligned: concepts, how-to guides, API reference, examples). Built with MkDocs Material from [`docs/`](docs/) and deployed to GitHub Pages on every push to `main`. +--- -Build the site locally: +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. -```bash -uv sync --group docs -make docs-serve # http://localhost:8000 -``` +Full docs (concepts, how-to guides, API reference, examples) are at . ## Install @@ -440,6 +441,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 From 473a2181c439cbade148cc6fb5892ebcc48f0447 Mon Sep 17 00:00:00 2001 From: Nitin Kanukolanu Date: Fri, 8 May 2026 19:07:36 -0400 Subject: [PATCH 3/3] chore: remove redundant docs link --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index 6cabbfe..eae10e2 100644 --- a/README.md +++ b/README.md @@ -14,8 +14,6 @@ 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. -Full docs (concepts, how-to guides, API reference, examples) are at . - ## Install ```bash