Conversation
- Port mkdocs.yml to zensical.toml (nav, theme, extensions, mkdocstrings) - Add scripts/convert_notebooks.py to convert example/workshop notebooks to Markdown at build time (Zensical does not yet support mkdocs-jupyter); each page links back to the original notebook - Update docs workflows: build with zensical, deploy site/ to gh-pages via peaceiris/actions-gh-pages; keep Netlify PR previews - Swap mkdocs dependencies for zensical in requirements_docs.txt - Remove docs/overrides (mkdocs-jupyter download button, now obsolete)
📝 WalkthroughWalkthroughThis PR migrates the docs pipeline from MkDocs to Zensical, adds notebook-to-Markdown conversion for docs notebooks, and updates the build, deploy, dependency, and ignore rules around the new generated site output. ChangesMkDocs to Zensical Migration
Estimated code review effort: 4 (Complex) | ~45 minutes Sequence Diagram(s)sequenceDiagram
participant Workflow as docs.yml / docs-build.yml
participant Script as scripts/convert_notebooks.py
participant Zensical as zensical build
participant Pages as GitHub Pages
Workflow->>Script: run notebook conversion
Script-->>Workflow: generated .md files
Workflow->>Zensical: build site from converted docs
Zensical-->>Workflow: ./site output
Workflow->>Pages: deploy ./site with actions-gh-pages
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
Migrates the documentation site from MkDocs + Material to Zensical, including notebook-to-Markdown conversion at build time and updates to CI workflows for GitHub Pages and Netlify previews.
Changes:
- Add
zensical.tomlconfiguration replacingmkdocs.yml(nav/theme/markdown extensions + mkdocstrings handler config). - Add
scripts/convert_notebooks.pyand ignore generated notebook Markdown outputs. - Update documentation workflows to run notebook conversion +
zensical build, and adjust docs dependencies accordingly.
Reviewed changes
Copilot reviewed 7 out of 8 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
zensical.toml |
New Zensical site configuration replacing MkDocs config (nav/theme/extensions/mkdocstrings). |
scripts/convert_notebooks.py |
Converts docs/examples and docs/workshops notebooks to Markdown for Zensical builds. |
requirements_docs.txt |
Removes MkDocs packages and adds Zensical-related doc build dependencies. |
mkdocs.yml |
Removes legacy MkDocs configuration. |
docs/overrides/main.html |
Removes MkDocs theme override previously used for notebook download UI. |
.gitignore |
Ignores generated .md files produced from notebooks during docs builds. |
.github/workflows/docs.yml |
Switches GitHub Pages deployment to Zensical + notebook conversion + gh-pages action. |
.github/workflows/docs-build.yml |
Switches Netlify PR preview build from MkDocs to Zensical + notebook conversion. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
🚀 Deployed on https://6a4c27f3d47fe3600befbb9d--opengeos.netlify.app |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
requirements_docs.txt (1)
10-21: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
nbconvert/nbformatnot present in this file's diff.
docs-build.ymlinstalls docs dependencies solely via this file, andscripts/convert_notebooks.pyrequiresnbformatandnbconvert. If these packages aren't already elsewhere in this file (outside the shown diff), thedocs-build.ymlconversion step will fail at runtime. As per PR objectives, "The docs requirements are updated to remove mkdocs-* packages and use Zensical, mkdocstrings-python, and nbconvert instead," sonbconvertshould be explicitly added here — please confirm it's present.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@requirements_docs.txt` around lines 10 - 21, The docs requirements list is missing an explicit dependency needed by the notebook conversion step. Verify that requirements_docs.txt includes nbconvert alongside nbformat, since docs-build.yml relies on this file and scripts/convert_notebooks.py imports both. If nbconvert is not already present elsewhere in the file, add it in the docs dependency list near the other documentation packages so the docs build can run successfully.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/workflows/docs.yml:
- Around line 6-7: The workflow currently grants workflow-level contents: write,
which is broader than needed and lacks an explanation. Move the write permission
to the deploy job in the docs workflow so only that job can push to gh-pages,
and add a short comment near the permission explaining why deploy needs write
access. Use the existing deploy job and permissions section to locate the
change.
- Line 26: The deploy step using peaceiris/actions-gh-pages@v4 should be pinned
to an immutable commit SHA instead of a mutable tag. Update the action reference
in the docs publishing workflow so the gh-pages deployment still works with
contents: write and gh-pages, but is locked to a specific revision of
peaceiris/actions-gh-pages for supply-chain safety.
In `@scripts/convert_notebooks.py`:
- Around line 50-53: The notebook conversion loop in
convert_notebook/NOTEBOOK_DIRS currently aborts the whole script on the first
parse or export failure. Wrap each per-notebook conversion in the main loop with
exception handling, log which nb_path failed and which ones succeeded before it,
and continue processing the remaining notebooks. At the end of the script,
return a non-zero exit status if any notebook conversion failed so CI still
fails cleanly.
---
Outside diff comments:
In `@requirements_docs.txt`:
- Around line 10-21: The docs requirements list is missing an explicit
dependency needed by the notebook conversion step. Verify that
requirements_docs.txt includes nbconvert alongside nbformat, since
docs-build.yml relies on this file and scripts/convert_notebooks.py imports
both. If nbconvert is not already present elsewhere in the file, add it in the
docs dependency list near the other documentation packages so the docs build can
run successfully.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 8331f7dd-9eb6-451b-8087-74cb6798d247
📒 Files selected for processing (8)
.github/workflows/docs-build.yml.github/workflows/docs.yml.gitignoredocs/overrides/main.htmlmkdocs.ymlrequirements_docs.txtscripts/convert_notebooks.pyzensical.toml
💤 Files with no reviewable changes (2)
- docs/overrides/main.html
- mkdocs.yml
- Install requirements_docs.txt in the docs deploy workflow instead of an ad-hoc package list (Copilot) - Run zensical build --clean --strict in both docs workflows to match the validated command and fail fast on warnings (Copilot) - Scope contents: write permission to the deploy job with an explanatory comment instead of workflow-level (CodeRabbit) - Pin peaceiris/actions-gh-pages to the v4 commit SHA for supply-chain safety (CodeRabbit) - Continue past per-notebook conversion failures and exit non-zero at the end so one bad notebook doesn't hide the rest (CodeRabbit)
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/workflows/docs.yml:
- Around line 21-24: The docs workflow build step can’t reliably find the
zensical console script because it may be installed under ~/.local/bin by pip
install --user. Update the workflow so the zensical command is available before
the build step in the docs job, either by removing --user from the pip installs
or by adding the user bin directory to PATH via GITHUB_PATH. Make the fix in the
workflow steps that install requirements and then run zensical build --clean
--strict.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: bccc9964-ebe8-40e7-8bd9-eacf8288138b
📒 Files selected for processing (3)
.github/workflows/docs-build.yml.github/workflows/docs.ymlscripts/convert_notebooks.py
| pip install --user -r requirements.txt -r requirements_dev.txt -r requirements_docs.txt | ||
| pip install --user . | ||
| # - name: PKG-TEST | ||
| # run: | | ||
| # python -m unittest discover tests/ | ||
| - run: python -m pip install --upgrade pip | ||
| - run: pip install mkdocs-material mkdocstrings mkdocstrings-python mkdocs-git-revision-date-plugin mkdocs-jupyter ipykernel | ||
| - run: mkdocs gh-deploy --force | ||
| - run: python scripts/convert_notebooks.py | ||
| - run: zensical build --clean --strict |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🌐 Web query:
Does GitHub Actions ubuntu-latest runner include ~/.local/bin in PATH for run steps
💡 Result:
Whether the ~/.local/bin directory is included in the PATH on GitHub Actions ubuntu-latest runners is inconsistent and can vary depending on the specific runner image version and architecture [1]. While some versions of the Ubuntu-hosted runners include /home/runner/.local/bin in the default PATH [2][1], others do not [3][4][5]. Because this behavior is not guaranteed across all runner environments, it is recommended practice to explicitly add ~/.local/bin to your PATH if your workflow depends on binaries installed there (e.g., via pip) [4][1]. To add it to the PATH for the remainder of your job, you can use the GITHUB_PATH environment file [6][7]: - name: Add ~/.local/bin to PATH run: echo "$HOME/.local/bin" >> $GITHUB_PATH Alternatively, if you only need it for a single step, you can modify the PATH variable within that step's script [8]. It is generally best to avoid relying on the default inclusion of this directory to ensure your workflows remain portable and predictable [4][1].
Citations:
- 1: https://github.com/actions/partner-runner-images/issues/25
- 2: Missing /home/runner/.local/bin to /etc/environment PATH in ubuntu 22.04 actions/actions-runner-controller#2540
- 3: Add /home/runner/.local/bin to PATH on Linux actions/runner-images#2455
- 4: pip installs binaries to location outside the PATH after upgrading to ubuntu-22.04 actions/runner-images#7476
- 5: All packages with CLI failing with '/home/runner/.local/bin' which is not on PATH actions/setup-python#99
- 6: https://github.com/github/docs/blob/main/content/actions/reference/workflows-and-actions/variables.md
- 7: https://stackoverflow.com/questions/68211182/how-to-set-system-path-variable-in-github-action-workflow
- 8:
PATHvariable not being updated actions/runner#2293
🏁 Script executed:
git ls-files .github/workflows/docs.yml .github/workflows/docs-build.yml && \
echo '--- docs.yml ---' && sed -n '1,120p' .github/workflows/docs.yml && \
echo '--- docs-build.yml ---' && sed -n '1,120p' .github/workflows/docs-build.ymlRepository: opengeos/segment-geospatial
Length of output: 3191
zensical needs to be on PATH before the build step. pip install --user can place the console script under ~/.local/bin, which GitHub Actions does not guarantee is on PATH for run: steps, so zensical build --clean --strict may fail with command not found. Drop --user, or add $HOME/.local/bin to GITHUB_PATH before the build step.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.github/workflows/docs.yml around lines 21 - 24, The docs workflow build
step can’t reliably find the zensical console script because it may be installed
under ~/.local/bin by pip install --user. Update the workflow so the zensical
command is available before the build step in the docs job, either by removing
--user from the pip installs or by adding the user bin directory to PATH via
GITHUB_PATH. Make the fix in the workflow steps that install requirements and
then run zensical build --clean --strict.
Summary
Migrates the documentation site from MkDocs + Material to Zensical, the successor static site generator from the Material for MkDocs team.
zensical.tomlreplacesmkdocs.yml, porting the full nav (Examples, Workshops, API Reference), theme (light/dark palettes following system preference, GitHub repo icon), markdown extensions, and mkdocstrings configuration.mkdocs-jupyter, soscripts/convert_notebooks.pyconverts all notebooks underdocs/examples/anddocs/workshops/to Markdown at build time with nbconvert. Each generated page starts with a badge linking to the original notebook on GitHub (replacing the old theme-override download button). The generated.mdfiles are gitignored.docs.ymlnow builds withzensical buildand deployssite/togh-pagesviapeaceiris/actions-gh-pages(replacingmkdocs gh-deploy).docs-build.ymlkeeps the Netlify PR preview, just swapping in the conversion step andzensical build.requirements_docs.txtdrops allmkdocs-*packages in favor ofzensical+mkdocstrings-python+nbconvert.Testing
zensical build --clean --strictpasses locally with no issues (5.4s full build).CNAMEcopied intosite/for the custom domain.pre-commit run --all-filespasses.Notes
git-revision-dateplugin has no Zensical equivalent yet, so the page-revision dates are dropped for now (on Zensical's roadmap).Summary by CodeRabbit
New Features
Changes
Chores