Add a Sphinx documentation site (GitHub Pages)#107
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a full Sphinx documentation site under doc/ (Markdown via MyST, API autodoc, RTD theme) and updates CI to build/deploy it to GitHub Pages, while trimming the README down to a quickstart that links to the published site.
Changes:
- Build out Sphinx docs content (getting started, configuration reference, custom generators, tips, API autodoc) and update
doc/conf.pyaccordingly. - Update docstrings in several modules to render cleanly under Sphinx autodoc.
- Add a docs GitHub Actions workflow and update packaging extras for docs dependencies; slim
README.mdto point users at the site.
Reviewed changes
Copilot reviewed 15 out of 15 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Replaces long README walkthrough with quickstart + links to the published docs. |
| pyproject.toml | Adds myst-parser to the docs extra. |
| doc/tips.md | New “Tips & recipes” docs page. |
| doc/index.rst | Removes the old quickstart-generated index stub (switching to Markdown). |
| doc/index.md | New docs landing page and toctree. |
| doc/getting-started.md | New installation/CLI/worked-example page. |
| doc/custom-generators.md | New guide for custom generators and hooks. |
| doc/configuration.md | New configuration reference with option tables and explanations. |
| doc/conf.py | Sphinx config updates for MyST, napoleon, theme, and version sourcing. |
| doc/api.rst | New autodoc-driven API reference page. |
| cppwg/writers/module_writer.py | Docstring formatting tweaks for clean autodoc output. |
| cppwg/writers/method_writer.py | Docstring formatting tweaks for clean autodoc output. |
| cppwg/writers/class_writer.py | Docstring formatting tweaks for clean autodoc output. |
| cppwg/info/package_info.py | Docstring formatting tweaks for clean autodoc output. |
| .github/workflows/docs.yml | New workflow to build docs on PRs/pushes and deploy to Pages from develop. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Build out the previously-empty doc/ Sphinx setup into a full site and slim the README to a quickstart that links to it. Configuration was only documented in the README tips and example configs; this adds a dedicated, searchable Configuration Reference. - doc/: index, getting-started, configuration (new option reference), custom-generators, tips, and an autodoc API page; Markdown via MyST, RTD theme, autodoc from the source docstrings. - conf.py: MyST + napoleon, .md sources, version single-sourced from the installed package metadata (regex fallback over pyproject.toml for a bare checkout, avoiding tomllib which is 3.11+ only). - Fix docstring RST markup so the autodoc build is clean under -W. - README: trimmed to install + quick start + links to the site. - pyproject: add myst-parser to the docs extra. - .github/workflows/docs.yml: build on push/PR, deploy to GitHub Pages on develop. Co-Authored-By: Claude Opus 4.8 <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
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.
Fixes #106
Build out the previously-empty doc/ Sphinx setup into a full site and slim the README to a quickstart that links to it. Configuration was only documented in the README tips and example configs; this adds a dedicated, searchable Configuration Reference.