Skip to content

Fix docs build warnings and treat new warnings as errors - #741

Merged
janosg merged 3 commits into
mainfrom
fix-docs-build-warnings
Nov 16, 2026
Merged

janosg merged 3 commits into
mainfrom
fix-docs-build-warnings

Conversation

@janosg

@janosg janosg commented Nov 15, 2026 •

Copy link
Copy Markdown
Member

What problem do you want to solve?

The docs build emitted 91 warnings and several pages rendered incorrectly. For example, the scipy_lbfgsb docs showed "'_' allowed only in math mode" instead of a formula. This PR fixes all warnings, makes the build fail on new ones and speeds the build up.

Rendering fixes

  • Escape underscores inside \text{} and \textsf{} in optimizer docstrings (scipy, nag, tao, tranquilo, gfo).
  • Document the attributes of 16 dataclasses with one docstring per attribute instead of a class level Attributes: section. The sections duplicated the autodoc member entries, which caused 65 "duplicate object description" warnings. Affected are the constraints, OptimizeResult, NumdiffOptions, MultistartOptions, ScalingOptions, IterationHistory and MultiStartIterationHistory.
  • Set PLOTLY_RENDERER=notebook_connected for notebook execution. The plots in how_to_add_optimizers and bayes_opt_tutorial were silently dropped because they only had a JSON representation.
  • Fix the paths of the eight animations in explanation_of_numerical_optimizers.md.
  • EP-00 included the root CODE_OF_CONDUCT.md that was removed in Use NumFocus' code of conduct #619. It now includes .github/CODE_OF_CONDUCT.md.
  • Fix two broken cross-references and the heading levels in bayes_opt_tutorial.ipynb and code_of_conduct.md.
  • Add a docstring to OptimizeLogReader and correct the description of FlatSDCorrConstraint, which was copied from ProbabilityConstraint.
  • Render bibliography entries, the * in signatures, figure captions and the mermaid diagram in the Markdown files for llms.txt. The exporter dropped them with a warning.

Build changes

  • docs/Makefile now builds with -W --keep-going -j auto: warnings fail the build and sources are read (including notebook execution) in parallel.
  • Notebook kernels are killed directly after execution. A graceful shutdown waited about two seconds for joblib workers in every notebook that uses n_cores.
  • The parallel examples use n_cores=2 instead of 4 or 6, and the bootstrap tutorial uses 2,000 instead of 10,000 draws in one example.

From-scratch build times on a 12-core Mac: 155 s sequential, 107 s with -j 2, 55 s with -j auto. The notebook changes reduced the sequential time from 188 s.

Things to know

  • Two myst-nb warning types are suppressed in conf.py: mystnb.unknown_mime_type, because bokeh always emits extra mime types next to the HTML that is rendered, and mystnb.mime_priority, because interactive figures are left out of the Markdown export on purpose.
  • myst-nb has no option for the kernel shutdown, so conf.py changes the default of nbclient.NotebookClient.shutdown_kernel.
  • todo_emit_warnings is only enabled for local builds, so a .. todo:: now fails locally but not on Read the Docs.
  • Parallel builds add two unlinked source pages for the stdlib modules enum and typing under _modules/.
  • how_to_algorithm_selection is still the slowest notebook (14 s). Nine seconds are the scipy_cobyla run; making it faster would change the content of the example.

Checklist

  • I have read the contributor guide.
  • I have described any additional validation I performed (e.g., manual checks, numerical comparisons, or benchmarks) and any remaining validation gaps.
  • I have added or updated tests for changed behavior. (Not applicable: the changes in src are docstrings only.)
  • I have updated documentation for user-facing changes.
  • I have linked any issues this PR resolves using Closes #XXXX. (No issue.)
  • I have described any substantial AI assistance and how I checked the result.
  • I have selected the appropriate base branch and described any remaining work.

Validation

  • I manually checked that a few places that did not render correctly before are fixed.
  • A from-scratch pixi run -e docs build-docs on top of current main finishes without warnings, both in the HTML build and in the Markdown sub-build for llms.txt.
  • A deliberately introduced warning makes the build exit with an error.
  • All 357 math expressions in the built HTML were run through MathJax 4 in Node without errors. The same check flags the original \textsf{convergence_ftol_rel}.
  • The built pages contain the previously missing plotly figures and animations, and the same 145 notebook output blocks with and without the faster kernel shutdown.
  • The tests and doctests of the touched modules and all pre-commit hooks pass.

Gaps: the full test suite and ty were not run locally, the pages were checked with scripts and not viewed in a browser, and the build was not tried on Linux. The first Read the Docs build may therefore show warnings that do not occur on macOS.

AI assistance

Claude Code diagnosed the warnings, made the changes and drafted this description. The result was checked with the builds and scripts listed above.

🤖 Generated with Claude Code

The docs build emitted 91 warnings and several pages rendered incorrectly.

Rendering fixes:
- Escape underscores inside \text{} and \textsf{} macros in optimizer
  docstrings. MathJax showed "'_' allowed only in math mode" instead of the
  formulas.
- Document dataclass attributes with one docstring per attribute instead of
  a class level Attributes section. The sections duplicated the autodoc
  member entries (65 "duplicate object description" warnings).
- Set PLOTLY_RENDERER for notebook execution. Figures in two notebooks were
  dropped because they only had a JSON representation.
- Fix the paths of the animations in the explanation of numerical
  optimizers, the include of the code of conduct in EP-00, two broken
  cross-references and several heading levels.
- Add a docstring to OptimizeLogReader and correct the description of
  FlatSDCorrConstraint.
- Render citations, the keyword-only marker in signatures, figure captions
  and mermaid diagrams in the Markdown files generated for llms.txt.

Build changes:
- Build with -W --keep-going so that new warnings fail the build.
- Build in parallel with -j auto.
- Kill notebook kernels directly after execution, use fewer cores in the
  parallel examples and fewer draws in the bootstrap tutorial.

Co-Authored-By: Claude <noreply@anthropic.com>
@review-notebook-app

Copy link
Copy Markdown

Check out this pull request on  ReviewNB

See visual diffs & provide feedback on Jupyter Notebooks.


Powered by ReviewNB

@codecov

codecov Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

Files with missing lines Coverage Δ
src/optimagic/constraints.py 92.48% <100.00%> (+0.58%) ⬆️
src/optimagic/differentiation/numdiff_options.py 98.61% <100.00%> (+0.12%) ⬆️
src/optimagic/logging/read_log.py 100.00% <ø> (ø)
src/optimagic/optimization/multistart_options.py 96.02% <100.00%> (+0.34%) ⬆️
src/optimagic/optimization/optimize_result.py 94.73% <100.00%> (+0.61%) ⬆️
src/optimagic/optimizers/gfo_optimizers.py 100.00% <ø> (ø)
src/optimagic/optimizers/nag_optimizers.py 94.26% <ø> (ø)
src/optimagic/optimizers/scipy_optimizers.py 97.75% <ø> (ø)
src/optimagic/optimizers/tao_optimizers.py 94.11% <ø> (ø)
src/optimagic/optimizers/tranquilo.py 99.51% <ø> (ø)
... and 2 more
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@janosg
janosg requested review from timmens and removed request for timmens November 15, 2026 16:20
@janosg
janosg merged commit 431d6a6 into main Nov 16, 2026
22 checks passed
@janosg
janosg deleted the fix-docs-build-warnings branch November 16, 2026 07:21
janosg added a commit that referenced this pull request Nov 16, 2026
Resolve conflicts with #727 and #741: keep the removal of read_log.py, of the
deprecated multistart options and of the deprecated type aliases in optimize.py.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant