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

Makefile

@@ -276,6 +276,7 @@ docs:
 	@echo "************************************"
 
 	-${PROTEUS_ENV} pip3 install sphinx sphinx_rtd_theme breathe exhale
+	@${PROTEUS_ENV} sh -c 'command -v dot' >/dev/null || { echo "graphviz 'dot' not found; inheritance diagrams need it (conda install graphviz)"; exit 1; }
 	cd docs && ${PROTEUS_ENV} PROTEUS=${PWD} make html
 
 	@echo "**********************************"

docs/Makefile

@@ -51,13 +51,23 @@ clean:
 	rm -rf source/api
 	rm -rf source/capi
 
-html: $(BUILDDIR)/capi/html/files.html source/api/modules.rst
+html: $(BUILDDIR)/capi/html/files.html source/api/proteus.rst
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)."
 
-source/api/modules.rst:
-	sphinx-apidoc --output-dir=source/api ../proteus "../**/*.so" "../proteus/tests" "../proteus/test_utils" "../proteus/config" --maxdepth=1 --separate --module-first --templatedir=source/_templates/apidoc
+source/api/proteus.rst:
+	# flcbdfWrappers.pyx: extension is commented out in setup.py (unbuilt,
+	# dead code) -- no compiled .so exists for autodoc to import.
+	# SWFlow/utils/SWEs_so.py: a parun-driven split-operator driver script,
+	# not an importable API module -- its top-level code sniffs sys.argv
+	# for a case file to __import__() by name, which only makes sense when
+	# invoked by parun itself and raises ModuleNotFoundError otherwise.
+	# --no-toc: apicapi.rst links directly to api/proteus.html (the
+	# top-level package page), never to the modules.rst index apidoc
+	# generates by default -- that page would be orphaned (not reachable
+	# from any toctree) and Sphinx warns accordingly, so skip generating it.
+	sphinx-apidoc --output-dir=source/api ../proteus "../**/*.so" "../proteus/tests" "../proteus/test_utils" "../proteus/config" "../proteus/flcbdfWrappers.pyx" "../proteus/SWFlow/utils/SWEs_so.py" --maxdepth=1 --separate --module-first --no-toc --templatedir=source/_templates/apidoc
 
 $(BUILDDIR)/capi/html/files.html:
 	mkdir -p ./build

docs/source/_templates/apidoc/package.rst_t

@@ -13,6 +13,10 @@
 {%- endfor %}
 {%- endmacro %}
 
+{%- if pkgname == "proteus" %}
+:orphan:
+
+{% endif %}
 {%- if is_namespace %}
 {{- [pkgname, "namespace"] | join(" ") | e | heading }}
 {% else %}

docs/source/conf.py

@@ -166,7 +166,6 @@ def linkcode_resolve(domain, info):
     'canonical_url': '',
     'analytics_id': '',
     'logo_only': True,
-    'display_version': True,
     'prev_next_buttons_location': 'bottom',
     'style_external_links': False,
     # 'vcs_pageview_mode': '',
@@ -290,8 +289,27 @@ def linkcode_resolve(domain, info):
 # not chapters.
 #latex_use_parts = False
 
+# LaTeX macros usable in docstring math, for both the HTML (MathJax) and
+# LaTeX builds: name -> (definition, number of arguments)
+math_macros = {
+    'grad': (r'\nabla', 0),
+    'deld': (r'\nabla\cdot', 0),
+    'outer': (r'\otimes', 0),
+    'ds': (r'\,\mathrm{d}s', 0),
+    'ten': (r'\mathbf{#1}', 1),
+    'mat': (r'\mathbf{#1}', 1),
+    'pd': (r'\frac{\partial #1}{\partial #2}', 2),
+    'od': (r'\frac{\mathrm{d} #1}{\mathrm{d} #2}', 2),
+}
+mathjax3_config = {
+    'tex': {'macros': {name: [body, nargs] if nargs else body
+                       for name, (body, nargs) in math_macros.items()}},
+}
+
 # Additional stuff for the LaTeX preamble.
-latex_elements['preamble'] = '\input{macros}'
+latex_elements['preamble'] = '\n'.join(
+    r'\providecommand{\%s}[%d]{%s}' % (name, nargs, body)
+    for name, (body, nargs) in math_macros.items())
 
 # If true, show page references after internal links.
 #latex_show_pagerefs = False
@@ -416,8 +434,6 @@ def linkcode_resolve(domain, info):
 
 graphviz_output_format = 'svg'
 
-mathjax_pth = "https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTM"
-
 breathe_projects = {
     "Proteus C++": "../build/capi/xml"
 }
@@ -450,4 +466,4 @@ def linkcode_resolve(domain, info):
 #    "exhaleExecutesDoxygen": True,
 #    #"exhaleUseDoxyfile": True,
 #    "exhaleDoxygenStdin":    exhaleDoxygenStdin
-#}
+#}

docs/source/tools/wave_tools.rst

@@ -104,7 +104,7 @@ If the relaxation zone method is used, then the class should be passed through t
    tank.setGenerationZones(x_n=True, waves=wave, dragAlpha=dragAlpha, smoothing = smoothing)
 
 
-Guidance for using the ``setUnsteadyTwoPhaseVelocityInlet`` and ``setGenerationZones`` functions are given in the :doc:`BoundaryConditions <./boundary_conditions>` and :doc:`Spatial Tools <./spatial_tools>` sections of the documentation
+Guidance for using the ``setUnsteadyTwoPhaseVelocityInlet`` and ``setGenerationZones`` functions is given in the ``BoundaryConditions`` API reference and the :doc:`Spatial Tools <./spatial_tools>` section of the documentation
 
 Simple examples of usage within the context of a 2D numerical tank can be found in `air-water-vv <https://github.com/erdc/air-water-vv/tree/master/2d/numericalTanks>`_
 

environment-dev-up.yml

@@ -62,3 +62,5 @@ dependencies:
   - cffi >=1.17.1
   - jupyterlab >=4.6
   - llvm-openmp >=22.1
+  # provides `dot` for the docs inheritance diagrams
+  - graphviz

proteus/DiagUtils.py

@@ -1,8 +1,5 @@
 """
 Module for diagnostic utilities
-
-.. inheritance-diagram:: proteus.DiagUtils
-   :parts: 1
 """
 from .EGeometry import *
 from .MeshTools import *

proteus/EGeometry.py

@@ -1,8 +1,5 @@
 """
 A simple implementation of basic 3D Euclidean Geometry
-
-.. inheritance-diagram:: proteus.EGeometry
-   :parts: 1
 """
 import math
 from math import *

proteus/FemTools.py

@@ -567,54 +567,55 @@ class BernsteinOnCube(LocalFunctionSpace):
     Bernstein polynomials on the unit nd-cube
 
     Bernstein basis functions on the reference nd-cube (nd <=3) with
-    coordinates xi[0],xi[1],and xi[2]. 
-    The basis functions are numbered as follows:     
-    ##############
-    # *** 2D *** #
-    ##############
-    ###########
-    # Order=1 #
-    ###########
-    3--2
-    |  |
-    0--1
-    ###########
-    # Order=2 #
-    ###########
-    3-6-2
-    | | |
-    7-8-5
-    | | |
-    0-4-1
-    ###########
-    # Order=3 #
-    ###########
-    3--9--8--2
-    |  |  |  |
-    10-14-15-7
-    |  |  |  |
-    11-12-13-6
-    |  |  |  |
-    0--4--5--1
-    ###########
-    # Order=4 #
-    ###########
-    3--12-11-10-2
-    |  |  |  |  |
-    13-22-23-24-9
-    |  |  |  |  |
-    14-19-20-21-8
-    |  |  |  |  |
-    15-16-17-18-7
-    |  |  |  |  |
-    0--4--5--6--1
-
-    NOTE (mql): *** The polynomials are defined for arbitrary order in 1D. 
-                    This definition is carried to multi-D via tensor products. 
-                *** The numbering is defined for arbitrary order (via funMap) in 2D.
-                *** TODO: Generalize numbering for 1D and 3D. 
-                *** TODO: The quad rule Lobatto edge alt must be generalized. 
-                *** TODO: define hessians and higher order deriavtives 
+    coordinates xi[0],xi[1],and xi[2].
+    The basis functions are numbered as follows::
+
+        ##############
+        # *** 2D *** #
+        ##############
+        ###########
+        # Order=1 #
+        ###########
+        3--2
+        |  |
+        0--1
+        ###########
+        # Order=2 #
+        ###########
+        3-6-2
+        | | |
+        7-8-5
+        | | |
+        0-4-1
+        ###########
+        # Order=3 #
+        ###########
+        3--9--8--2
+        |  |  |  |
+        10-14-15-7
+        |  |  |  |
+        11-12-13-6
+        |  |  |  |
+        0--4--5--1
+        ###########
+        # Order=4 #
+        ###########
+        3--12-11-10-2
+        |  |  |  |  |
+        13-22-23-24-9
+        |  |  |  |  |
+        14-19-20-21-8
+        |  |  |  |  |
+        15-16-17-18-7
+        |  |  |  |  |
+        0--4--5--6--1
+
+        NOTE (mql): *** The polynomials are defined for arbitrary order in 1D.
+                        This definition is carried to multi-D via tensor products.
+                    *** The numbering is defined for arbitrary order (via funMap) in 2D.
+                    *** TODO: Generalize numbering for 1D and 3D.
+                    *** TODO: The quad rule Lobatto edge alt must be generalized.
+                    *** TODO: define hessians and higher order deriavtives
     """
     from math import factorial 
 

proteus/LinearAlgebraTools.py

@@ -106,14 +106,14 @@ def petsc_load_IS(filename):
 def csr_2_petsc(size,csr):
     """ Create an petsc4py matrix from size and CSR information.
 
-    Parameters:
+    Parameters
     ----------
     size : tuple
         A 2-tuple with the number of matrix rows and columns.
     csr : tuple
         A 3-tuple with the sparse matrix csr information.
 
-    Returns:
+    Returns
     --------
     matrix : PETSc4py aij matrix
     """
@@ -365,14 +365,14 @@ def dense_numpy_2_petsc4py(dense_numpy, eps = 1.e-12):
 def csr_2_petsc_mpiaij(size,csr):
     """ Create an MPIaij petsc4py matrix from size and CSR information.
 
-    Parameters:
+    Parameters
     ----------
     size : tuple
         Two entires: (num_rows, num_cols)
     csr : tuple
         (row_idx, col_idx, vals)
 
-    Returns:
+    Returns
     --------
     matrix : PETSc4py MPIaij matrix
     """
@@ -389,11 +389,11 @@ def split_PETSc_Mat(mat):
     """ Decompose a PETSc matrix into a symmetric and skew-symmetric
         matrix
 
-    Parameters:
+    Parameters
     ----------
     mat : :class: `PETSc4py Matrix`
 
-    Returns:
+    Returns
     --------
     H : :class: `PETSc4py Matrix`
         Symmetric (or Hermitian) component of mat
@@ -552,6 +552,9 @@ def print_info(cls):
 
 class ParMat_petsc4py(p4pyPETSc.Mat):
     """  Parallel matrix based on petsc4py's wrappers for PETSc.
+
+    Parameters
+    ----------
     ghosted_csr_mat : :class:`proteus.superluWrappers.SparseMatrix`
         Primary CSR information for the ParMat.
     par_bs : int

proteus/LinearSolvers.py

@@ -1292,6 +1292,7 @@ class DofOrderInfo(object):
     """Base class for managing DOF ordering information
 
     Parameters
+    ----------
     dof_order_type : str
         This describes the type of dof ordering that will
         be constructed.  Currently supports: 'blocked'
@@ -4386,7 +4387,7 @@ def apply_ns(self,
 
         Arguments
         ---------
-        par_b : :vec:`petsc4py_vec`
+        par_b : petsc4py vector
         """
         # Check whether a global null space vector for a constant
         # pressure has been created.  If not, create one.
@@ -4454,7 +4455,7 @@ def apply_ns(self,
 
         Arguments
         ---------
-        par_b : :vec:`petsc4py_vec`
+        par_b : petsc4py vector
         """
         # Check whether a global null space vector for a constant
         # has been created.  If not, create one.

proteus/NonlinearSolvers.py

@@ -809,7 +809,7 @@ def solve(self,u,r=None,b=None,par_u=None,par_r=None):
 
 class ExplicitLumpedMassMatrix(Newton):
     """
-     This is a fake solver meant to be used with optimized code
+    This is a fake solver meant to be used with optimized code
     A simple iterative solver that is Newton's method
     if you give it the right Jacobian
     """
@@ -851,7 +851,7 @@ def no_solve(self,u,r=None,b=None,par_u=None,par_r=None):
 
 class ExplicitLumpedMassMatrixForRichards(Newton):
     """
-     This is a fake solver meant to be used with optimized code
+    This is a fake solver meant to be used with optimized code
     A simple iterative solver that is Newton's method
     if you give it the right Jacobian
     """
@@ -877,7 +877,7 @@ def solve(self,u,r=None,b=None,par_u=None,par_r=None):
 
 class ExplicitConsistentMassMatrixWithRedistancing(Newton):
     """
-     This is a fake solver meant to be used with optimized code
+    This is a fake solver meant to be used with optimized code
     A simple iterative solver that is Newton's method
     if you give it the right Jacobian
     """
@@ -982,7 +982,7 @@ def solve(self,u,r=None,b=None,par_u=None,par_r=None):
 
 class ExplicitConsistentMassMatrixForVOF(Newton):
     """
-     This is a fake solver meant to be used with optimized code
+    This is a fake solver meant to be used with optimized code
     A simple iterative solver that is Newton's method
     if you give it the right Jacobian
     """
@@ -1018,7 +1018,7 @@ def solve(self,u,r=None,b=None,par_u=None,par_r=None):
 
 class ExplicitConsistentMassMatrixForRichards(Newton):
     """
-     This is a fake solver meant to be used with optimized code
+    This is a fake solver meant to be used with optimized code
     A simple iterative solver that is Newton's method
     if you give it the right Jacobian
     """
@@ -1054,7 +1054,7 @@ def solve(self,u,r=None,b=None,par_u=None,par_r=None):
 
 class NewtonWithL2ProjectionForMassCorrection(Newton):
     """
-     This is a fake solver meant to be used with optimized code
+    This is a fake solver meant to be used with optimized code
     A simple iterative solver that is Newton's method
     if you give it the right Jacobian
     """

proteus/Norms.py

@@ -1,8 +1,5 @@
 """
 Tools for calculating norms on function spaces.
-
-.. inheritance-diagram:: proteus.Norms
-   :parts: 1
 """
 from .FemTools import *
 from .Quadrature import *

proteus/NumericalFlux.py

@@ -4511,7 +4511,7 @@ class RusanovNumericalFlux(RusanovNumericalFlux_Diagonal):
 
     .. math::
 
-       \bar{\lamda}= max |\vec f^{\prime} \cdot n\|
+       \bar{\lambda}= max |\vec f^{\prime} \cdot n\|
 
     Then we just apply apply numerical flux