docs(ci): publish MkDocs site to GitHub Pages#12
Conversation
There was a problem hiding this comment.
Pull request overview
This PR adds a GitHub Actions workflow to build and publish the repository’s existing MkDocs site to GitHub Pages, and updates MkDocs configuration to use the GitHub Pages URL as the canonical site_url.
Changes:
- Add a new
DocsGitHub Actions workflow that builds the MkDocs site withuvand deploys it to GitHub Pages. - Update
mkdocs.ymlto setsite_urltohttps://redis-developer.github.io/adk-redis/. - Add a
docsoptional dependency extra inpyproject.tomlto install MkDocs and the plugins used for the docs build.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
.github/workflows/docs.yml |
New workflow to build and deploy the MkDocs site to GitHub Pages on changes to docs and related inputs. |
mkdocs.yml |
Updates canonical site URL to match GitHub Pages hosting location. |
pyproject.toml |
Adds a docs extra for MkDocs and related plugins to reproduce the docs build locally. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| "mkdocs-llmstxt>=0.5", | ||
| "mkdocs-section-index>=0.3", | ||
| "mkdocs-autorefs>=1.2", | ||
| "mkdocs-macros-plugin>=1.0", |
There was a problem hiding this comment.
Fixed in 6c6dd0c: removed mkdocs-macros-plugin from the docs extra.
| - "mkdocs.yml" | ||
| - "src/adk_redis/**" | ||
| - "pyproject.toml" | ||
| - "uv.lock" |
There was a problem hiding this comment.
Fixed in 6c6dd0c: removed uv.lock from the paths filter.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: acc9e3d15c
ℹ️ 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".
| - "pyproject.toml" | ||
| - "uv.lock" | ||
| - ".github/workflows/docs.yml" | ||
| workflow_dispatch: |
There was a problem hiding this comment.
Allowing workflow_dispatch without a branch guard means anyone with permission to run Actions can publish docs from any branch, so unmerged or experimental content can overwrite the public GitHub Pages site when the deploy job runs. This is a production-facing risk for the docs site unless the github-pages environment is separately configured with branch protection, so the workflow should enforce main in YAML (for example via a deploy job if) instead of relying on repository settings.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 6c6dd0c: added if: github.ref == 'refs/heads/main' to the deploy job so workflow_dispatch from non-main branches cannot overwrite the live site.
Adds a GitHub Actions workflow that builds the `mkdocs.yml` configuration with the Material theme + mkdocstrings + llmstxt plugins, then deploys to GitHub Pages via `actions/deploy-pages@v4` (OIDC, no token needed). Changes: - `.github/workflows/docs.yml`: build + deploy on push to main when any docs source changes (docs/**, mkdocs.yml, src/**, pyproject.toml, uv.lock, the workflow itself). Also supports `workflow_dispatch` for manual triggers. - `mkdocs.yml`: switch `site_url` from the unresolved `https://ai.redis.io/adk/` to the GitHub Pages canonical URL `https://redis-developer.github.io/adk-redis/`. - `pyproject.toml`: new `[docs]` optional extra so contributors can reproduce the build with `uv sync --extra docs --extra all`. The workflow uses `mkdocs build` (not `--strict`) on purpose. There are 44 pre-existing griffe docstring/signature warnings in `tools/memory/*` (the Memory* tools' docstrings document parameters that don't appear in the actual function signatures). Those warnings are real and worth fixing, but should not block doc deploys. Tracked separately. Post-merge follow-ups: - Enable GitHub Pages on the repo (`Settings > Pages > Source: GitHub Actions`) so the deploy step has an environment to push to. Can be set via API: `gh api -X POST repos/.../pages -f build_type=workflow`.
- Remove mkdocs-macros-plugin from docs extra (not used in mkdocs.yml) - Remove uv.lock from workflow paths filter (no lockfile committed) - Add branch guard (if: github.ref == 'refs/heads/main') to deploy job so workflow_dispatch from non-main branches cannot overwrite the site
- Rename project to 'Redis Integrations for the Google Agent Development Kit' - Slim quickstart from 379 to 109 lines; delegate details to concepts/how-tos - Fix outdated class names (RedisWorkingMemorySessionService, RedisLongTermMemoryService) - Add semantic cache how-to covering RedisVL and LangCache providers - Update examples index to list all 9 examples with direct GitHub links - Remove 3 redundant example stub pages (fitness_coach, travel_agent_hybrid, redis_search_tools) - Fix broken internal links after stub page removal - Verify config defaults against source code (recency_boost, etc.) - Align sidebar layout with redisvl docs (full-width md-grid)
nkanu17
force-pushed
the
feat/github-pages-docs
branch
from
6c6dd0c to
642fd40
Compare
Summary
Wires up GitHub Pages so the existing
mkdocs.ymlsite (Material theme, mkdocstrings, llmstxt) is hosted at https://redis-developer.github.io/adk-redis/ instead of only living in the repo tree.What's in here
.github/workflows/docs.yml: build + deploy on push to main when any ofdocs/**,mkdocs.yml,src/adk_redis/**,pyproject.toml,uv.lock, or the workflow itself changes. Also supportsworkflow_dispatchfor manual triggers. Usesactions/deploy-pages@v4with OIDC (no token).mkdocs.yml: switchsite_urlfrom the unresolvedhttps://ai.redis.io/adk/to the GitHub Pages URL.pyproject.toml: new[docs]optional extra (mkdocs-material,mkdocstrings[python],mkdocs-llmstxt,mkdocs-section-index,mkdocs-autorefs,mkdocs-macros-plugin) so contributors can reproduce the build withuv sync --extra docs --extra all.Pre-existing issue, not addressed here
mkdocs build --strictwould fail on 44 griffe warnings insrc/adk_redis/tools/memory/{create,delete,get,prompt,search,update}.py: those docstrings document parameters that don't appear in the actual function signatures. The workflow usesmkdocs build(not--strict) on purpose so doc deploys aren't blocked. Worth a follow-up PR to fix the docstrings.Post-merge follow-up
GitHub Pages needs to be enabled on the repo (
Settings > Pages > Source: GitHub Actions) before the deploy step has an environment to push to. Can be set via:After that, the first push to main re-runs the workflow and the site goes live.
Test plan
uv sync --extra docs --extra allthenuv run mkdocs buildsucceeds locally (~1.9s, 44 pre-existing griffe warnings, site emitted tosite/).