Repository navigation
feat(docs): documentation site -- MkDocs Material + mkdocstrings on GitHub Pages - #10
Merged
Merged
Conversation
…itHub Pages Static-site generator selection (researched against Sphinx+Furo/MyST, Docusaurus, Starlight, VitePress, Hugo, Jekyll, mdBook, Zola): MkDocs + Material fits this repo best -- the existing docs are plain markdown with relative links and dollar-sign LaTeX that build unmodified, the toolchain stays pure-Python under uv, and mkdocstrings (griffe, static analysis) is the only first-class Python API autodoc outside Sphinx. Material 9.x is pinned <10 / MkDocs 1.x: MkDocs 2.0 is an incompatible rewrite, and the Material team's successor (Zensical) is the designated drop-in migration path once its plugin phase lands -- recorded in pyproject next to the pin. Site (https://cameronbrooks11.github.io/gerberdiff/): - landing page, existing guide/internals docs unchanged in nav - API reference via mkdocstrings (numpy docstring style) - Changelog + Contributing included via pymdownx.snippets - MathJax (arithmatex generic) for the LaTeX already used in docs - light/dark palette, search, edit-on-GitHub links Deploy: .github/workflows/docs.yml builds with 'mkdocs build --strict' on PRs and pushes; pushes to main deploy via actions/deploy-pages (Pages is configured for workflow deployment). Also: module docstring for the top-level package (surfaced by the API reference), absolute LICENSE link in CONTRIBUTING (was a dead relative link on the rendered site), docs badge + site link in README. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
SSG selection (researched, not defaulted)
Weighed MkDocs+Material against Sphinx (Furo/MyST), Docusaurus, Astro Starlight, VitePress, Hugo, Jekyll, mdBook, and Zola. MkDocs + Material + mkdocstrings wins for this repo:
docs/*.mdare plain markdown with relative links and$...$LaTeX — they build unmodified (arithmatex); every non-Python SSG needs front-matter surgery and offers no Python API autodocdocsdependency group), trivially CI'dMkDocs 2.0 caveat handled: 2.0 is an incompatible rewrite (plugins removed). Material 9.x is maintained and pinned to MkDocs 1.x; the Material team's successor Zensical is the designated drop-in migration path once its plugin phase lands. The pin (
mkdocs-material>=9.5,<10) and rationale are recorded inpyproject.toml.What's in the site
Deploy
.github/workflows/docs.yml:mkdocs build --stricton PRs (build gate, no deploy) and on pushes to main (deploy viaactions/upload-pages-artifact+actions/deploy-pages). Pages is already configured for workflow deployment. Site URL: https://cameronbrooks11.github.io/gerberdiff/Local
mkdocs build --strict: clean, 0.7 s. All repo gates green; new files ASCII-clean.🤖 Generated with Claude Code