Skip to content

docs: fix Sphinx build warnings; restore richards.cADR extension (1.9.x) - #43

Merged
cekees merged 4 commits into
1.9.xfrom
docfix-sphinx-warnings-1.9.x
Oct 13, 2026
Merged

docs: fix Sphinx build warnings; restore richards.cADR extension (1.9.x)#43
cekees merged 4 commits into
1.9.xfrom
docfix-sphinx-warnings-1.9.x

Conversation

@cekees

@cekees cekees commented Oct 12, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Your docfix-sphinx-warnings branch (3dac55e + 6f21604), cherry-picked onto 1.9.x, with two changes:

Everything else is unchanged: the Sphinx warning fixes (104 → 3), the raw-string fixes for LaTeX docstrings whose \n/\t/\r were being interpreted as escapes, the apidoc exclusions, and the restored richards.cADR Extension.

About the restored extension

  • proteus/richards/cADR.cpp compiles with the entry as written (checked standalone with clang 21 and libc++; -Iproteus/richards isn't needed). With it built, import proteus.richards.ADR works.
  • The module still doesn't run. Running test/richards/adr_1d through it fails in getResidual. Three argsDict["elementMaterialTypes"] = ..., lines have trailing commas that make the value a tuple, and after fixing those, delta_x_ij is None. richards.ADR began as a skeleton and isn't finished. That work is tracked in proteus.richards.ADR is unimportable: richards.cADR extension not built erdc/proteus#1285; this PR only makes the module importable and gets it through the docs build.

Docstring math and graphviz (9eb0efd)

  • Macros: \deld, \grad, \ten, \pd, \od, \mat, \outer, \ds are now defined once in conf.py (math_macros). mathjax3_config and the LaTeX preamble are both generated from it; the preamble used to \input{macros}, a file that isn't in the repo. Without the definitions, MathJax drew 93 of these as red \grad-style text and Sphinx gave no warning.
  • Corrupted docstrings: 17 more docstrings were made raw. They still had \vec/\frac/\alpha/\beta/\tau turned into control characters, the same bug the first commit fixed elsewhere. Only docstrings changed: the AST with docstrings blanked is identical before and after.
  • TeX errors: fixed a \left( without \right) and {rho} in the k-epsilon docs, \ten \bar{D} → \ten{\bar{D}}, Python % (a TeX comment) → \bmod, and the \lamda/\alph typos. TI_base's equation is math again.
  • Result: all 206 formulas in proteus docstrings typeset in MathJax 3 with no errors and no undefined macros. Checked in a browser against a Sphinx 9.1 build of every docstring that contains math.
  • graphviz: added to environment-dev-up.yml; the 35 modules with inheritance diagrams need dot. make docs now fails if dot is missing instead of silently dropping the diagrams. The four diagrams removed earlier (DiagUtils, EGeometry, Norms, RefUtils) warn "No classes found" whether or not dot is present, so removing them was correct.
  • Corrected the first commit's message, which said graphviz had been added when it hadn't (rewritten and force-pushed).

Testing

  • All 23 changed .py files pass py_compile with -W error::SyntaxWarning.
  • The docs build itself was verified on the original branch (base 1.9.0) and wasn't rerun here. The cherry-pick onto 1.9.x had no conflicts.

The branch also applies cleanly to main; I'll forward-port it if you want it there too.

🤖 Generated with Claude Code

@cekees @claude
docs: fix invalid escape sequence in LaTeX preamble string
592a0c1 
'\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
This was referenced Oct 12, 2026
Open
Merged
cekees and others added 2 commits October 13, 2026 10:02
@cekees @claude
docs: fix Sphinx build errors/warnings and a real richards.ADR import…
5d2f028 
… 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
@cekees @claude
docs: define LaTeX macros for docstring math; add graphviz
9eb0efd 
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>
@cekees
cekees force-pushed the docfix-sphinx-warnings-1.9.x branch from bd779c8 to 9eb0efd Compare October 13, 2026 08:02
@cekees cekees mentioned this pull request Oct 13, 2026
Merged
cekees
cekees commented Oct 13, 2026
View reviewed changes

@cekees cekees left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good.

@cekees
cekees merged commit 4a357e3 into 1.9.x Oct 13, 2026
5 checks passed
@cekees
cekees deleted the docfix-sphinx-warnings-1.9.x branch October 13, 2026 14:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@cekees