docs: standardize on Sphinx + Furo (the "xeos stack") - #26
Merged
Conversation
Adopt the shared documentation standard used across the x* packages, replacing the alabaster setup: - docs/source/ -> flat docs/ layout - alabaster -> Furo theme; nbsphinx -> myst-nb (notebooks rendered from committed outputs, never executed at build time; documented in the new contributor guide) - recursive-autosummary API reference (docs/api.md + autosummary templates) - index.rst / installation.rst -> MyST Markdown - .readthedocs.yaml -> pip (docs/requirements.txt); add a pip-based CI docs job - per-package accent (#b45309) and a "View on GitHub" button linking to the repo Also fixes a malformed RST bullet list in GriddedRegion.to_gr's docstring that the new (exhaustive) API reference surfaced under -W. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Brings in the git-tag versioning (hatch-vcs), the `sectionate >= 0.3.4, < 0.4` pin, and `regionmask >= 0.13` — the last two are what fix this branch's red CI (unpinned sectionate resolved an xgcm that had completed the `boundary` -> `padding` rename, which `initialize_spherical_grid` still uses). Conflict: `.readthedocs.yaml`. Both sides rewrote the same block. Kept this branch's pip-based docs config (`docs/conf.py`, `docs/requirements.txt`, no conda) and main's `post_checkout` unshallow/fetch-tags job, which the flat layout still needs — `docs/conf.py` titles the docs with the installed version, and hatch-vcs resolves that from the git tag. Comment repointed at the new path. Same reason, same fix on the other side: the CI `docs` job now checks out with `fetch-depth: 0`, matching what main gave the `build` job. Co-Authored-By: Claude Opus 5 (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.
Standardize regionate docs on Sphinx + Furo (the "xeos stack")
Overhauls regionate's documentation to match the shared, sleek style being
adopted across the
x*package family, replacing the old alabaster setup. Thisis the second package on the standard (after xbudget); the setup comes from a
shared
docs-template.What changes
nbsphinx→myst-nb(Markdown + notebooks in one).nb_execution_mode = "off") —committed with outputs; documented in the new contributor guide.
docs/source/→ flatdocs/;index.rst/installation.rst→ MyST..readthedocs.yaml→ pip (docs/requirements.txt); adds apip-based
docsjob to CI (regionate had none). Both use-W/ fail-on-warning.#b45309) + a “View on GitHub” button.One source change
GriddedRegion.to_gr's docstring had a malformed RST bullet list (no blank line,misaligned continuations) that the new exhaustive API reference surfaces under
-W. Fixed to render cleanly — content unchanged.Verification
Builds clean with warnings-as-errors, against regionate + its real deps:
All pages, the 4 example notebooks (rendered from committed outputs), and the full
recursive API reference render.
🤖 Generated with Claude Code