Repository navigation
docs: fix Sphinx build warnings; define math macros; restore richards.cADR extension - #47
Merged
Merged
Conversation
'\input{macros}' triggered a SyntaxWarning ("\i" is an invalid escape
sequence) under current Python; make it a raw string.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PcVEQMRyBkdnv6pDKykJRt
… bug Drives docs_build warnings from 104 down to 3 (0 errors, build succeeds clean). Root-caused via napoleon+docutils isolation testing, not just grepped from the build log. Real bugs (not cosmetic): - proteus/richards/ADR.py does `from .cADR import *`, but the richards.cADR Extension entry was dropped from setup.py in merge 9e2aca5 (2026-08-12), leaving richards.ADR unimportable. Restored it, mirroring richards.cRichards (erdc#1285). - Several docstrings (PresInc.Coefficients, PostProcessingTools, SubgridError, TimeIntegration, mprans/Pres.Coefficients) used LaTeX like \nabla/\tau/\theta/\rho in a non-raw string -- Python silently interpreted \n/\t/\r as real newline/tab/CR characters, corrupting the docstring content itself, not just its RST rendering. Fixed with r""" in each case, same class of bug as the conf.py `\input` fix. - docs/Makefile's sphinx-apidoc invocation tried to autodoc proteus/flcbdfWrappers.pyx (extension commented out in setup.py, no compiled .so exists) and proteus/SWFlow/utils/SWEs_so.py (a parun-driven split-operator script that sniffs sys.argv and __import__()s a case file by name -- fails outside of parun). Excluded both from the apidoc scan. Cosmetic (widespread but mechanical): missing blank lines before numpydoc `Parameters`/`Returns`/`Notes` headers, mismatched continuation indentation, bullet/definition lists glued to a preceding paragraph without a blank line, a bare `.. math:` (single colon, not a directive at all), `-mavx`-unrelated stray formatting -- across LinearAlgebraTools, LinearSolvers, FemTools, NonlinearSolvers, SimTools, StepControl, Viewers, WaveTools, mbd/CouplingFSI, mprans/{BodyDynamics, BoundaryConditions,MoveMeshMonitor}. Also dropped three vestigial `.. inheritance-diagram::` directives (DiagUtils, EGeometry, Norms, RefUtils) pointing at modules that define no classes at all. Doc-build plumbing: apidoc's default modules.rst index page is never linked from this project's toctree (apicapi.rst hyperlinks straight to api/proteus.html instead) -- generating it produced a permanent "not included in any toctree" warning. Switched to `--no-toc` and marked the new orphan (api/proteus.rst itself, only reached via that same bare hyperlink) with `:orphan:` via a package.rst_t template tweak, scoped to just the top-level package page. Also removed sphinx_rtd_theme's removed `display_version` option, fixed a `:doc:` link to a boundary_conditions page that doesn't exist. The inheritance-diagram directives that do have classes need graphviz's `dot` to render; that was present in the env this was tested in but is not added here (see the follow-up commit). Remaining 3 warnings, investigated and left as genuinely benign: - TI_base:1 -- isolated napoleon+docutils reproduction of this exact docstring (alone, and combined with __init__'s per autoclass_content='both') parses with zero warnings; a minimal standalone Sphinx project autodoc-ing just this class also reproduces nothing. Sphinx's location attribution for this one appears to be wrong in the full build, not a real defect in the referenced content. - WaveTools.NewWave.phi / WaveTools.RandomWaves.phi -- an ambiguous cross-reference between two sibling classes' identically-named attributes; no specific docstring line introduces it via an explicit role, so there's no single place to point a fix at. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PcVEQMRyBkdnv6pDKykJRt
Docstring math uses custom macros (\deld, \grad, \ten, \pd, \od, \mat,
\outer, \ds) that were never defined for the HTML build, so MathJax drew
93 of them as red "\grad"-style text with no build warning. The LaTeX
preamble did `\input{macros}`, a file that is not in the repo. Define
them once in conf.py (math_macros) and generate both mathjax3_config
and the LaTeX preamble from that. Drop the unused `mathjax_pth`.
Make 17 more docstrings raw that still had \v, \f, \a, \b, \t or \r
turned into control characters (\vec, \frac, \alpha, \beta, \tau/\ten),
the same bug class as the previous commit. Only docstrings change: each
file's AST with docstrings blanked is identical before and after.
Fix TeX errors MathJax reported: \left( closed by `)` and \frac{1}{rho}
in the k-epsilon docstrings, `\ten \bar{D}` -> `\ten{\bar{D}}`, Python
`%` (a TeX comment) -> \bmod in three PostProcessingTools formulas, and
the \lamda/\alph typos. Restore TI_base's equation as math.
All 206 formulas in proteus docstrings now typeset in MathJax 3 with no
errors and no undefined macros.
Add graphviz to environment-dev-up.yml, which the inheritance diagrams
need for `dot`, and make `make docs` fail if `dot` is missing rather
than silently drop the diagrams.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
main dropped xtensor and get_xtensor_include(); the restored richards.cADR entry (cherry-picked from 1.9.x) still called it, which would make setup.py raise NameError. Use get_pybind_include_dirs() and list proteus/pyarray.h in depends, like richards.cRichards. proteus/richards/cADR.cpp compiles against main's headers. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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.
Forward-port of #43 to main: the same three commits, cherry-picked without conflicts, plus one main-only fix.
Main-only fix (c790970): main removed xtensor and
get_xtensor_include(), but the restoredrichards.cADRExtension still called it, which would makesetup.pyraiseNameError. It now usesget_pybind_include_dirs()and listsproteus/pyarray.hin its depends, matchingrichards.cRichards.proteus/richards/cADR.cppcompiles against main's headers (checked standalone with clang 21 and libc++).Everything else is as described in #43:
\deld,\grad,\ten,\pd,\od,\mat,\outer,\ds) defined once inconf.py, for both MathJax and the LaTeX preamble.dotcheck formake docs.futureaddition is not included.Testing, against main's tree
proteus/contains control characters..pyfiles, onlyconf.pyandsetup.pychange anything besides docstrings; every other file's AST with docstrings blanked is identical toorigin/main..pyfiles passpy_compilewith-W error::SyntaxWarning.This PR shares no files with #44 (the argsDict fix on main), and the two merge cleanly.
🤖 Generated with Claude Code