Adding docs and examples to github pages#88
Conversation
- Add `.github/workflows/deploy-docs.yml`: two-job pipeline (build with `uv run mkdocs build --strict` → upload Pages artifact → deploy via `actions/deploy-pages@v4`). Triggers on push to main with path filters plus `workflow_dispatch`. - Add `site_url: https://cubert-hyperspectral.github.io/cuvis.sdk/` to `mkdocs.yml` so Material emits the correct sitemap and absolute OG/canonical links. To go live: Settings → Pages → Source → "GitHub Actions", then push any docs change or run the workflow manually.
- Add a strict mkdocs build check on PRs and before each mike deploy so broken links or missing generated pages fail CI instead of publishing a broken site. - Serialize nightly and versioned deploys with a shared concurrency group to avoid racing pushes to gh-pages. - Correct the Examples overview: the generated example pages are Python-only. - Keep trailing prose in notebook-derived pages (_parse_notebook now flushes a final markdown-only section) and add tests covering it. - Fix mkdocs feature flag typo: content.code.annotation -> content.code.annotate.
|
One config note for the Python API reference: please keep Re: GitHub Pages — the source switch to the |
Add index.md to the mkdocs-llmstxt sections so the overview page is in the generated llms.txt / llms-full.txt, and reword the description to say the index covers the guide and Python API (the C/C++ reference stays browsable on the site). The generated mkdoxy pages are deliberately not listed so the strict build keeps no dependency on plugin ordering.
The Unreleased section logged the rebrand and the CI/review fixes but not the headline change this branch makes: migrating the docs site into the repo with mike versioning, mkdoxy/mkdocstrings API reference, notebook example pages, and the llms.txt index.
nghorbani
left a comment
nghorbani
left a comment
There was a problem hiding this comment.
Approving. Reviewed the docs/CI migration and the example-page generator.
Fixes pushed on the branch: strict-build gate (PR check + before each mike deploy), shared deploy concurrency, examples-overview wording (Python-only), the _parse_notebook trailing-cell drop (with tests), the content.code.annotate typo, and the Home page added to the llms.txt index.
One post-merge step remains for a maintainer: once the first mike deploy creates gh-pages, switch Settings → Pages to deploy from that branch (flipping before it exists would 404 the live site). And please keep allow_inspection: false in the mkdocstrings config. LGTM.
2 participants
Summary
Migrates the documentation site from
cuvis.docinto this repo and publishes it to GitHub Pages, with versioned docs, generated API reference, and an LLM-readable index.cuvis.doc.mike— av*.*.*tag publishes that version (aliasedlatest); pushes tomainpublish adevbuild.mkdoxy(Doxygen), Python viamkdocstrings(static/griffe;allow_inspection: falseis deliberate — importingcuvisexits without the installed SDK).llms.txt/llms-full.txtindex viamkdocs-llmstxt.CI / review hardening (added on this branch)
Docs build checkworkflow runsmkdocs build --stricton PRs, and a strict build also runs before eachmike deploy— broken links / missing generated pages now fail CI instead of publishing.concurrencygroup across the nightly + versioned deploys so they can't race each other's push togh-pages._parse_notebookno longer drops a notebook's trailing markdown cell; added parser/macro tests.content.code.annotation→content.code.annotatetypo fix.llms.txtindex; description clarified.Maintainer follow-ups
mike deploycreates thegh-pagesbranch, switch Settings → Pages → Deploy from branch:gh-pages/ (root). The site currently publishes from a Pages Actions build, so flipping beforegh-pagesexists would 404 the live site.allow_inspection: falsein themkdocstringsconfig.Publishing a versioned doc release
git tag vX.Y.Z && git push origin vX.Y.Ztriggersdeploy-docs-versioned.yml, which builds and publishes that version aslatest(same tag-driven pattern ascuvis-ai). Pushes tomainkeep thedevbuild current.