From 674f75b4fba0ebf2315bbbdf189fb7522be59a91 Mon Sep 17 00:00:00 2001 From: silviana amethyst Date: Thu, 9 Jul 2026 13:08:33 +0000 Subject: [PATCH] fix(docs): escape absolute-value bars in docstrings that RST read as 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. --- python/bertini/operators.py | 2 +- python_bindings/src/mpfr_export.cpp | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/python/bertini/operators.py b/python/bertini/operators.py index bbdb5e646..444f6e1f5 100644 --- a/python/bertini/operators.py +++ b/python/bertini/operators.py @@ -118,7 +118,7 @@ def f(x, *args, **kwargs): round = _numeric_only('round', _nh.round, "Round to N DECIMAL digits, staying mp-native.") # noqa: A001 sum = _numeric_only('sum', _nh.sum, "Sum of a collection, staying mp-native.") # noqa: A001 norm = _numeric_only('norm', _nh.norm, "Euclidean (2-)norm, as real_mp.") -is_real = _numeric_only('is_real', _nh.is_real, "Is every coordinate real (|imag| < tol)?") +is_real = _numeric_only('is_real', _nh.is_real, "Is every coordinate real (abs(imag) < tol)?") __all__ = [ diff --git a/python_bindings/src/mpfr_export.cpp b/python_bindings/src/mpfr_export.cpp index aeb567adc..a7fea0f68 100644 --- a/python_bindings/src/mpfr_export.cpp +++ b/python_bindings/src/mpfr_export.cpp @@ -355,7 +355,7 @@ namespace bertini{ +[](Vec const& p, Vec const& q, double tol) -> bool { return bertini::IsDistinct(p, q, tol); }, (arg("p"), arg("q"), arg("tol")), - "True if points p and q differ by more than tol in the infinity norm (max_i |p_i - q_i|); " + "True if points p and q differ by more than tol in the infinity norm (max_i abs(p_i - q_i)); " "False if they are the same to within tol. The tolerance-based point-equality test " "(issue #304). Accepts complex_mp or real_mp vectors; different-length points are distinct."); def("is_distinct_up_to",