Skip to content

Docs: build from uv.lock in CI and on Read the Docs, move to Sphinx 9 and pydata-sphinx-theme - #809

Merged
milton-minervino merged 12 commits into
MAIF:developfrom
milton-minervino:feature/docs-ci
Oct 29, 2026
Merged

milton-minervino merged 12 commits into
MAIF:developfrom
milton-minervino:feature/docs-ci

Conversation

@milton-minervino

Copy link
Copy Markdown
Collaborator

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.py trained 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

  • Read the Docs and a new Docs CI job install the same locked environment: uv sync --locked --no-editable --no-default-groups --group doc --extra report.
  • docs/conf.py is now plain configuration. Notebook copying and demo report generation move to scripts/prepare_docs.py, which writes to gitignored folders (docs/tutorials/, docs/_generated/). report.html is still published at the same URL, so the README link keeps working.
  • Warnings fail the build in CI (-W --keep-going), on Read the Docs (fail_on_warning: true) and in make docs.

Tooling

  • Sphinx 9, pydata-sphinx-theme, myst-nb (pandoc is no longer needed), sphinx-design, sphinx-copybutton, ipython (notebook syntax highlighting) and intersphinx.
  • Warnings went from 692 to 0:
    • fixed the reST errors in docstrings;
    • turned two notebook cell attachments into image files;
    • added missing cell ids to one notebook.
    • Two notebook-only warning types are suppressed, with a comment in conf.py: skipped heading levels, and VS Code Data Wrangler outputs.

API reference

  • Each class documents all its public members, so new methods appear automatically. This adds 8 missing SmartPlotter plots, to_smartpredictor and define_style.
  • New pages: backends, report customization (ReportTemplate, ReportBlockMixin and its built-in blocks), standalone plots, and the NLP API (torch is mocked, so the build doesn't install it).
  • A summary table at the top links to every object. The existing page URLs are kept.

Content

  • Home page: removed the duplicated feature lists, added cards to the four sections and an NLP section.
  • Getting started:
    • removed the dependency versions from 2020;
    • fixed the step count;
    • corrected which parameter is required;
    • removed project_info_file, which generate_report no longer accepts.
  • Installation:
    • every extra is listed, with quoted pip commands;
    • removed extras that don't exist;
    • replaced ~150 lines of JupyterLab 1–3 and ipywidgets setup with a short Plotly check.
  • Tutorial sections get readable titles. Fixed the "dictionnary" misspelling in docstrings, error messages and tutorials.

How to test

uv run --group doc make docs

This prepares the sources, builds with -W and opens docs/_build/html/index.html.

Notes for reviewers

  • .readthedocs.yml can only be exercised on Read the Docs. We should first merge it into develop to see if the RTD workflow passes.
  • The two extracted tutorial images use raw.githubusercontent.com/.../master/... URLs, like the existing tutorial images, so they show only after merging to master.
  • External links aren't checked in CI. Run make -C docs linkcheck occasionally, for example before a release.

Follow-ups

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.
@milton-minervino milton-minervino linked an issue Oct 22, 2026 that may be closed by this pull request
@codecov

codecov Bot commented Oct 22, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 0% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.08%. Comparing base (2f70bef) to head (0972aad).

Files with missing lines Patch % Lines
shapash/utils/check.py 0.00% 2 Missing ⚠️

❌ 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           
Files with missing lines Coverage Δ
shapash/backend/lime_backend.py 88.77% <ø> (ø)
shapash/explainer/nlp_plotter.py 96.42% <ø> (ø)
shapash/explainer/smart_explainer.py 76.74% <ø> (ø)
shapash/explainer/smart_plotter.py 77.88% <ø> (ø)
shapash/explainer/smart_predictor.py 82.10% <ø> (ø)
shapash/plots/plot_bar_chart.py 90.34% <ø> (ø)
shapash/plots/plot_feature_importance.py 81.60% <ø> (ø)
shapash/webapp/nlp_app.py 94.22% <ø> (ø)
shapash/utils/check.py 80.09% <0.00%> (ø)
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@milton-minervino milton-minervino added documentation Improvements or additions to documentation enhancement New feature or request labels Oct 23, 2026
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.
Comment thread docs/_templates/sidebar.html Outdated

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 ?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
@guillaume-vignal
guillaume-vignal self-requested a review October 29, 2026 12:57
@milton-minervino
milton-minervino merged commit efa3759 into MAIF:develop Oct 29, 2026
9 of 10 checks passed
@milton-minervino
milton-minervino deleted the feature/docs-ci branch October 29, 2026 15:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs build and deployment

2 participants