Share README prose into docs; add Examples/Performance pages - #22
Merged
Conversation
Rework the Sphinx docs so the landing page and new pages pull their prose
directly from README.md instead of duplicating it, keeping a single source
of truth. Fenced HTML-comment markers (doc:intro, doc:install, etc.) delimit
the shared slices, which MyST {include} pulls in via start-after/end-before.
- index.md: landing page includes the intro, installation, and quick-start
slices, plus a lightweight static figure (akima_step) and a link to the
new Examples page.
- examples.md (new): hosts the demo and grid animations with their shared
explanations and footnote references, keeping the heavier GIFs off the
landing page.
- performance.md (new): includes the performance-snapshot slice.
- conf.py: serve the repo-root assets/ via html_static_path so pages can
reference _static/akima_*.{gif,png} without moving or duplicating the
folder; add custom.css for light/dark image switching that follows Furo's
theme toggle (body[data-theme]) rather than the README's OS-based <picture>.
Builds clean under the strict -W CI flag.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Replace the broken shields.io PyPI placeholder with a placeholder Zenodo DOI badge (to be wired up on release), and break the badge row after the license badge so the CI badges wrap to a second line. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Zenodo's badge URLs key off the numeric repository ID (972418978), not owner/repo. The badge resolves once the Zenodo GitHub integration is enabled and a release mints a DOI. 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
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.
Summary
Reworks the Sphinx docs so pages pull their prose directly from
README.mdinstead of duplicating it, establishing a single source of truth. The oldindex.mdhad hand-copied intro/install/quick-start text that could drift from the README.HTML-comment markers (
<!-- doc:intro:start -->,doc:install,doc:quickstart,doc:corners,doc:grid,doc:regen,doc:perf,doc:footnotes) fence the shared slices in the README (invisible on GitHub), and MyST{include}pulls them in viastart-after/end-before.Structure
index.md— landing page includes the intro, installation, and quick-start slices, plus a lightweight static figure (akima_step, ~40 KB) and a link to Examples. Stays light and fast.examples.md(new) — hosts the demo + grid animations with their shared explanations and footnote references, keeping the ~1.8 MB of GIFs off the landing page.performance.md(new) — includes the performance-snapshot slice.Assets & theming
conf.pyserves the repo-rootassets/viahtml_static_path(contents land in_static/), so pages reference_static/akima_*.{gif,png}without moving or duplicating the folder — which matters becausepyakima.demosand the GitHub README both write/readassets/at the repo root.docs/_static/custom.cssdrives light/dark image switching. The README's<picture>keys off the OSprefers-color-scheme; these docs images instead follow Furo's own theme toggle (body[data-theme]) so the toggle and image stay in sync. That's why the docs use per-page<img class="only-light/only-dark">rather than the shared README markup.Notes / follow-ups
akima_step_*.png. A purpose-rendered single-frame still can be dropped in later without structural changes.Verification
Builds clean under the strict
-W --keep-goingflag used by the docs CI workflow; all imagesrcs resolve to real files in_static/, footnotes resolve, and included prose renders on every page.🤖 Generated with Claude Code