docs: rename demo notebooks to descriptive slugs (#840)#861
docs: rename demo notebooks to descriptive slugs (#840)#861anevolbap wants to merge 4 commits intopymc-labs:mainfrom
Conversation
Require lowercase hyphen-separated filenames with method names spelled out in full, and document that renames must add a rediraffe redirect.
Rename all 31 demo notebooks from abbreviated snake_case (its_pymc, rd_skl, ...) to descriptive hyphen-separated names (interrupted-time-series-pymc, regression-discontinuity-sklearn, ...) for better SEO and readability. Update the toctree in index.md, the CI skip-list, and three internal cross-references (in custom_pymc_models.ipynb, panel-fixed-effects.ipynb, and inverse-propensity-latent.ipynb) to the new filenames. Legacy URLs are preserved in a separate commit via sphinxext-rediraffe. Refs pymc-labs#840.
Add sphinxext-rediraffe to the docs extras and configure a 31-entry rediraffe_redirects map in conf.py so old notebook URLs (e.g. notebooks/its_pymc.html) redirect to the new descriptive slugs. Protects social-media and blog links that point at the historical URLs. Refs pymc-labs#840.
|
Check out this pull request on See visual diffs & provide feedback on Jupyter Notebooks. Powered by ReviewNB |
Documentation build overview
70 files changed ·
|
|
This PR's failing |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #861 +/- ##
==========================================
- Coverage 94.60% 94.59% -0.02%
==========================================
Files 80 80
Lines 12764 12764
Branches 770 770
==========================================
- Hits 12076 12074 -2
- Misses 485 486 +1
- Partials 203 204 +1 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
@drbenvincent this is ready for review. CI is green after merging Quickest way to validate the redirects: open an old-slug URL on the RTD preview, e.g. https://causalpy--861.org.readthedocs.build/en/861/notebooks/its_pymc.html. It should redirect to For the notebook-heavy diff, the ReviewNB link above gives a cell-aware view. Thanks! |
2 participants
Rename demo notebooks to descriptive slugs
Fixes #840.
Summary
its_pymc,rd_skl, ...) to descriptive hyphen-separated slugs (interrupted-time-series-pymc,regression-discontinuity-sklearn, ...).sphinxext-rediraffe.AGENTS.mdnaming policy, toctree, CI skip-list, and internal cross-references.Why
Search engines treat underscores as a single token, so
its_pymcis indexed as an opaque string. Descriptive, hyphen-separated slugs tokenize into words that match real queries ("interrupted time series python", "regression discontinuity pymc"). Rediraffe keeps old URLs working.Commits
docs: update notebook naming policy in AGENTS.mddocs: rename demo notebooks to descriptive hyphen-case slugs— 31 renames viagit mv(history preserved), plusindex.md,skip_notebooks.yml, and three notebook cross-references (custom_pymc_models.ipynb,panel-fixed-effects.ipynb,inverse-propensity-latent.ipynb).docs: preserve legacy notebook URLs with sphinxext-rediraffe— add the extension to thedocsextras and a 31-entry redirect map inconf.py.Testing
.ipynbexists, no old-slug files remain, every current notebook has exactly one redirect entry.prek run --files <changed-files>passes.sphinx-buildnot executed locally (docs env needs rebuilding against current Sphinx). CI will exercise the redirect generation.Checklist
sphinxext-rediraffeinpyproject.tomldocs extras.notebooks/its_pymc.htmlredirects.