Skip to content

Tutorial notebooks: fix spelling, headings, stale content and grammar - #814

Merged
milton-minervino merged 4 commits into
MAIF:developfrom
milton-minervino:docs/tutorial-rewrite
Oct 29, 2026
Merged

milton-minervino merged 4 commits into
MAIF:developfrom
milton-minervino:docs/tutorial-rewrite

Conversation

@milton-minervino

@milton-minervino milton-minervino commented Oct 23, 2026 •

Copy link
Copy Markdown
Collaborator

Why

#809 listed a review of the notebook titles and headings as a follow-up. Many tutorials, mostly the older ones, also had spelling mistakes, headings that skipped levels, leftover HTML, outdated references and ungrammatical sentences. Since the notebooks are now part of the docs site, these show up directly in the docs.

What changed

Four commits, one per kind of change:

  1. Spelling, heading levels and HTML (22 notebooks)

    • Fixed misspellings that recur across notebooks ("supervized", "explanability", "dictionnary", "instanciate", …).
    • Heading levels no longer skip (e.g. ## → ####), and each notebook has a single H1. The myst.header warning suppression is removed from docs/conf.py.
    • Replaced <br /> and <b> with Markdown.
  2. Stale content (14 notebooks)

    • Removed references to the acv backend, which no longer exists (quality01, expl06), and rewrote the quality01 comments to match the SHAP methods the notebook actually compares.
    • Aligned intros and contents lists with what each notebook does (expl01, expl06, plot04).
    • Webapp launch pointers now link to scripts/webapp_launch_*.py, which moved in refactor: move examples of webapp launch into scripts #779. The commented examples now use app.run, since Dash 3 removed app.run_server.
    • NLP overview: the model is described as an emotion classifier, not a sentiment one, and the note about running the webapp without the model now matches the API.
  3. Titles and headings (23 notebooks)

    • Short descriptive headings instead of instructions ("First step: You need to Declare and Compile SmartExplainer" → "Compile the SmartExplainer").
    • Notebook titles lose redundant prefixes ("Shapash Tutorial -", "Tutorial:"), and method or package names are formatted as code (e.g. "scatter_plot_prediction and lift_curve_plot", "Using category_encoders").
  4. Grammar (22 notebooks)

    • Rewrote ungrammatical sentences in the older tutorials without changing their meaning, and fixed the most broken intro openers and contents lists.

Apart from the two run_server comments, only markdown cells change: no code, outputs or cell IDs. Filenames are unchanged, so tutorial URLs stay the same.

How to test

uv run --group doc make docs

The build passes with -W and no warnings, including without the myst.header suppression.

@milton-minervino milton-minervino added the documentation Improvements or additions to documentation label Oct 23, 2026
@milton-minervino
milton-minervino requested review from guerinclement and guillaume-vignal and removed request for guillaume-vignal October 23, 2026 10:04
@milton-minervino
milton-minervino marked this pull request as ready for review October 23, 2026 10:04
@codecov

codecov Bot commented Oct 23, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.08%. Comparing base (efa3759) to head (85bbbd9).

Additional details and impacted files
@@           Coverage Diff            @@
##           develop     #814   +/-   ##
========================================
  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:
  • ❄️ 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.

Heading levels no longer skip, so the myst.header warning no longer needs
to be suppressed in the docs build.
Replace references to the removed acv backend, align intros and contents
lists with what the notebooks do, point webapp launch examples to the
scripts folder and use app.run, as Dash 3 removed app.run_server.
Use short descriptive headings instead of instructions, fix the wording
of bare step labels, and drop redundant prefixes from notebook titles.
Rewrite ungrammatical sentences in the older tutorials without changing
their meaning, and clean up the intro openers and contents lists.
@milton-minervino
milton-minervino merged commit 4af903b into MAIF:develop Oct 29, 2026
10 checks passed
@milton-minervino
milton-minervino deleted the docs/tutorial-rewrite branch October 29, 2026 15:57
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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants