Repository navigation
Fix docs build warnings and treat new warnings as errors - #741
Merged
Merged
Conversation
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>
|
Check out this pull request on See visual diffs & provide feedback on Jupyter Notebooks. Powered by ReviewNB |
Codecov Report✅ All modified and coverable lines are covered by tests.
🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What problem do you want to solve?
The docs build emitted 91 warnings and several pages rendered incorrectly. For example, the
scipy_lbfgsbdocs 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
\text{}and\textsf{}in optimizer docstrings (scipy, nag, tao, tranquilo, gfo).Attributes:section. The sections duplicated the autodoc member entries, which caused 65 "duplicate object description" warnings. Affected are the constraints,OptimizeResult,NumdiffOptions,MultistartOptions,ScalingOptions,IterationHistoryandMultiStartIterationHistory.PLOTLY_RENDERER=notebook_connectedfor notebook execution. The plots inhow_to_add_optimizersandbayes_opt_tutorialwere silently dropped because they only had a JSON representation.explanation_of_numerical_optimizers.md.CODE_OF_CONDUCT.mdthat was removed in Use NumFocus' code of conduct #619. It now includes.github/CODE_OF_CONDUCT.md.bayes_opt_tutorial.ipynbandcode_of_conduct.md.OptimizeLogReaderand correct the description ofFlatSDCorrConstraint, which was copied fromProbabilityConstraint.*in signatures, figure captions and the mermaid diagram in the Markdown files forllms.txt. The exporter dropped them with a warning.Build changes
docs/Makefilenow builds with-W --keep-going -j auto: warnings fail the build and sources are read (including notebook execution) in parallel.n_cores.n_cores=2instead 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
conf.py:mystnb.unknown_mime_type, because bokeh always emits extra mime types next to the HTML that is rendered, andmystnb.mime_priority, because interactive figures are left out of the Markdown export on purpose.conf.pychanges the default ofnbclient.NotebookClient.shutdown_kernel.todo_emit_warningsis only enabled for local builds, so a.. todo::now fails locally but not on Read the Docs.enumandtypingunder_modules/.how_to_algorithm_selectionis still the slowest notebook (14 s). Nine seconds are thescipy_cobylarun; making it faster would change the content of the example.Checklist
srcare docstrings only.)Closes #XXXX. (No issue.)Validation
pixi run -e docs build-docson top of currentmainfinishes without warnings, both in the HTML build and in the Markdown sub-build forllms.txt.\textsf{convergence_ftol_rel}.Gaps: the full test suite and
tywere 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