Repository navigation
Docs: build from uv.lock in CI and on Read the Docs, move to Sphinx 9 and pydata-sphinx-theme - #809
Conversation
Read the Docs and a new CI job install the locked doc environment with uv (non-editable, so the build imports the packaged code). Notebook copying and demo report generation move from conf.py to scripts/prepare_docs.py, whose outputs are gitignored. Warnings fail the build in CI, on Read the Docs and in make docs.
Replace the frozen Sphinx 4.5 / sphinx_material / nbsphinx stack. myst-nb removes the pandoc requirement, and ipython restores notebook syntax highlighting. The API pages document every public member instead of hand-picked lists, and new pages cover the backends and the NLP API. Notebook cell attachments become image files, and one notebook gets the cell ids its nbformat version requires.
Fix outdated content: dependency versions from 2020, a generate_report parameter that no longer exists, nonexistent extras, and the JupyterLab 1-3 widget setup Shapash doesn't need. List every extra with quoted pip commands, give tutorial sections readable titles, and hide the empty section navigation on single pages.
Codecov Report❌ Patch coverage is
❌ Your patch check has failed because the patch coverage (0.00%) is below the target coverage (90.00%). You can increase the patch coverage or adjust the target coverage. Additional details and impacted files@@ Coverage Diff @@
## develop #809 +/- ##
========================================
Coverage 86.08% 86.08%
========================================
Files 115 115
Lines 11825 11825
Branches 2158 2158
========================================
Hits 10180 10180
Misses 1009 1009
Partials 636 636
🚀 New features to boost your workflow:
|
Add plotly to the intersphinx inventories so the figure types in the API reference link to its documentation. Setting SHAPASH_DOCS_OFFLINE=1 skips downloading the inventories, for builds without network access such as behind a proxy.
Place the section links next to the logo, as pandas and scikit-learn do. In dark mode the logo now uses the light-on-dark version from the webapp, resized to the navbar logo's size, instead of the dark one that blended into the background.
The copy button now leaves out the ">>> ", "... " and shell prompts, so the copied examples run as pasted. The "Show Source" link, which only showed the reST source of the page, is removed, as in pandas and scikit-learn.
There was a problem hiding this comment.
the purpose of this file was to change version of shapash documentation, is there a new way of doing it with the last version of sphynx ?
There was a problem hiding this comment.
Good catch. That template only worked with sphinx_material: it replaced the theme's whole sidebar and used its CSS classes and templates. Since we switched to a new theme, it went away.
Version switching should still works through the Read the Docs switch dropdown menu. I could not check it yet since it must be first merged into develop. It's enabled on the project and is added to every build whatever the theme, so the new docs keep it.
If we want a selector back in the page itself, the simplest way is to reuse the old script as a pydata-sphinx-theme header dropdown. It would read the same Read the Docs version data, so there's nothing to maintain. pydata's built-in switcher also works, but it needs a switcher.json updated at each release. I'd add the dropdown in a follow-up once a second version uses the new theme, or in this PR if you'd rather have it now.
List the dev version and the latest patch of each minor release, generated from the git tags by scripts/prepare_docs.py. Hide the Read the Docs flyout on the new pages; old releases keep it.
Why
The docs were built only on Read the Docs, with frozen 2022 tooling (Sphinx 4.5, sphinx_material, nbsphinx). Breakage showed up only after a merge, hidden among ~690 warnings.
conf.pytrained a model and copied notebooks into the source tree every time it loaded, and part of the public API was missing from the hand-written member lists.Closes #801
What changed
Build and deployment
DocsCI job install the same locked environment:uv sync --locked --no-editable --no-default-groups --group doc --extra report.docs/conf.pyis now plain configuration. Notebook copying and demo report generation move toscripts/prepare_docs.py, which writes to gitignored folders (docs/tutorials/,docs/_generated/).report.htmlis still published at the same URL, so the README link keeps working.-W --keep-going), on Read the Docs (fail_on_warning: true) and inmake docs.Tooling
conf.py: skipped heading levels, and VS Code Data Wrangler outputs.API reference
SmartPlotterplots,to_smartpredictoranddefine_style.ReportTemplate,ReportBlockMixinand its built-in blocks), standalone plots, and the NLP API (torchis mocked, so the build doesn't install it).Content
project_info_file, whichgenerate_reportno longer accepts.How to test
This prepares the sources, builds with
-Wand opensdocs/_build/html/index.html.Notes for reviewers
.readthedocs.ymlcan only be exercised on Read the Docs. We should first merge it into develop to see if the RTD workflow passes.raw.githubusercontent.com/.../master/...URLs, like the existing tutorial images, so they show only after merging tomaster.make -C docs linkcheckoccasionally, for example before a release.Follow-ups
-n), once the docstring types are normalized (Enforce type hints and numpy-style docstrings in the quality gates #804).tuto-shapash-regression-report.ipynbandnlp/overview.ipynb, and a review of notebook titles, headings.