Clear every Sphinx warning - #73
Merged
Merged
Conversation
Six warnings on every docs build, so a new one would not stand out. All cosmetic, none changing what a reader sees, but they were the noise that hid a real problem. - icon_style was the one parameter whose line-block continuation lines lacked the leading two-space indent, so docutils ended the block early and warned twice. Every other parameter in the docstring is already written this way. - make_waffle's ":param **kwargs:" opened inline strong that never closed. Escaped as \*\*kwargs and the docstring made raw, matching what functional.py already does. - MyST generates no heading anchors unless asked, so subplots.md's link to value_scaling_and_auto_sizing.md#value-scaling silently resolved to nothing. Set myst_heading_anchors. - plot_with_characters_or_icons.md linked to font_awesome_integration.html, a built artifact Sphinx cannot resolve. Point at the source file so it is checked. - language was None, which Sphinx warns about and falls back to "en" for. Set it. Verified in the rendered HTML rather than only by the warning count: the icon_style text is intact, **kwargs renders literally with no stray backslashes, the #value-scaling anchor now exists in the target page, and the Font Awesome link resolves to a page that is actually built.
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
1 participant
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.
Six warnings on every documentation build, so a new one would not stand out among them. All cosmetic, none changing what a reader sees, but they were the noise that made it easy to miss that the site was not building at all (#72).
Line block ends without a blank line(x2)icon_styleis the one parameter whose line-block continuation lines lack the leading two-space indent, so docutils ends the block earlyInline strong start-string without end-stringmake_waffle's:param **kwargs:opens inline strong that never closes\*\*kwargsand make the docstring raw, matching whatfunctional.pyalready doeslocal id not found: 'value-scaling'subplots.md's link tovalue_scaling_and_auto_sizing.md#value-scalingresolved to nothingmyst_heading_anchorscross-reference target not found: 'font_awesome_integration.html'Invalid configuration value: 'language = None'"en", which is what Sphinx was falling back to anywayTwo of these were real broken links that looked fine in the page: the
#value-scalingfragment went nowhere, and the Font Awesome link was only working by accident of the output layout.Verified in the rendered HTML, not just by the warning count
A warning count going to zero can also mean the content stopped rendering, so I checked the output:
icon_styletext is intact, as a proper line block.**kwargsrenders literally, with no stray backslashes leaking through.id="value-scaling"now exists in the target page, and the link points at it.../font_awesome_integration.html, which is built.Suite is green (234 tests), including the docstring tests that assert every parameter is documented with its real default.
blackclean.Stacked on nothing, but best merged after #72, which is the fix that actually matters.