fix(docs): escape absolute-value bars that RST misread as substitutions (v3.1.0 docs deploy) - #313
Merged
Conversation
…substitutions The versioned-docs deploy (build_docs.yml runs `sphinx-build -b html -W`) failed on the v3.1.0 release: three docstrings wrote absolute-value/norm notation with bare pipes -- `max_i |p_i - q_i|` (is_distinct_up_to, surfaced twice: multiprec + top-level re-export) and `|imag| < tol` (operators.is_real). In reStructuredText `|word|` is a *substitution reference*, so Sphinx tried to resolve undefined substitutions "p_i - q_i" and "imag" and errored; with -W (warnings-as-errors) the docs build died. Reword both to `abs(...)`, which reads cleanly in Sphinx HTML and plain help() and carries no RST metacharacters. (The other |...| docstrings in the tree are already safe -- wrapped in ``inline literals`` or inside code blocks -- so they are left as-is.) This did not affect the released wheels (docstrings only): 3.1.0 is on PyPI and the GitHub Release is published; only the docs site deploy failed. Verified locally by reproducing the exact failing command (sphinx-build -b html -W --keep-going) -- now 'build succeeded', no substitution errors. Escapes surfaced because the -W html build runs only at docs-deploy time, not in PR CI.
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.
The v3.1.0 versioned-docs deploy failed.
build_docs.ymlrunssphinx-build -b html -W(warnings-as-errors), and three docstrings wrote absolute-value / norm notation with bare pipes:
In reStructuredText
|word|is a substitution reference, so Sphinx tried to resolve undefinedsubstitutions
p_i - q_iandimagand errored out.is_distinct_up_to(#305) andis_real(#306)both landed in the 3.1.0 line.
Fix
Reword the two source strings to
abs(...)—max_i abs(p_i - q_i)andabs(imag) < tol— whichread cleanly in Sphinx HTML and plain
help()and carry no RST metacharacters. The other|…|docstrings in the tree are already safe (wrapped in
inline literalsor inside code blocks) andare left untouched.
Not a package problem
Docstrings only — the released wheels are unaffected. 3.1.0 is already on PyPI and the GitHub
Release is published; only the docs-site deploy failed.
Verified
Reproduced the exact failing command locally (
sphinx-build -b html -W --keep-going): nowbuild succeeded, zero substitution errors.Root-cause note (for the post-3.1.0 CI pass)
The
-b html -Wbuild runs only at docs-deploy time, not in PR CI (PR CI runs-b doctest,which passed). So this whole class of RST/docstring error is invisible until release. Running the
-Whtml build in PR CI would have caught it — worth adding alongside #312.