docs: rename demo notebooks to descriptive slugs (#840)#861
Conversation
|
Check out this pull request on See visual diffs & provide feedback on Jupyter Notebooks. Powered by ReviewNB |
Documentation build overview
139 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.87% 94.87%
=======================================
Files 85 85
Lines 13174 13174
Branches 793 793
=======================================
Hits 12499 12499
Misses 479 479
Partials 196 196 ☔ 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! |
|
Thanks @anevolbap ! Would you mind fixing the conflicts (probably because of #868). If it becomes annoying feel free to open a new PR (I hate git + notebooks) :) |
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.
anevolbap
force-pushed
the
issue-840-notebook-slug-seo
branch
from
7acf98b to
38bb031
Compare
|
Done, rebased onto current main. The git + notebooks pain is exactly why I use jupytext and marimo in my own projects. |
you are a wise man :) |
juanitorduz
left a comment
juanitorduz
left a comment
There was a problem hiding this comment.
@drbenvincent could you please take a look at this one as well, just to doubble check? 🙏
3 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.