Clean up docs and docstrings

Fix various formatting errors causing warnings in docs build.

Author: xylar

conda_package/docs/Makefile

@@ -12,7 +12,7 @@ BUILDDIR      = _build
 #   make versioned-html             # normal
 #   make versioned-html WERROR=1    # treat warnings as errors
 ifeq ($(WERROR),1)
-  SPHINXWARNOPTS = -nW --keep-going
+  SPHINXWARNOPTS = -W --keep-going
 else
   SPHINXWARNOPTS =
 endif

conda_package/docs/api.rst

@@ -1,3 +1,5 @@
+.. _api_reference:
+
 #############
 API reference
 #############
@@ -375,8 +377,8 @@ Visualization
    :toctree: generated/
 
    MpasToXdmf
-   MpasToXdmf.load()
-   MpasToXdmf.convert_to_xdmf()
+   MpasToXdmf.load
+   MpasToXdmf.convert_to_xdmf
    main
 
 .. currentmodule:: mpas_tools.viz.mesh_to_triangles

conda_package/docs/conf.py

@@ -179,7 +179,7 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/', None),
+    'python': ('https://docs.python.org/3/', None),
     'numpy': ('http://docs.scipy.org/doc/numpy/', None),
     'xarray': ('http://xarray.pydata.org/en/stable/', None),
     'geometric_features':

conda_package/docs/interpolation.rst

@@ -1,8 +1,8 @@
-.. _mesh_interpolation:
-
 .. |---| unicode:: U+2014  .. em dash, trimming surrounding whitespace
    :trim:
 
+.. _mesh_interpolation:
+
 *************
 Interpolation
 *************

conda_package/docs/mesh_conversion.rst

@@ -266,9 +266,23 @@ Extensibility and Limitations
 - For advanced use cases (e.g., custom mask types or additional properties),
   see the source code and docstrings for guidance.
 
-See also the API documentation for :py:mod:`mpas_tools.mesh.mask` for further details.
+See also the API documentation for :py:mod:`mpas_tools.mesh.mask` for further
+details.
 
-See also the API documentation for :py:mod:`mpas_tools.mesh.mask` for further details.
+.. code-block::
+
+    $ compute_mpas_region_masks --help
+    usage: compute_mpas_region_masks [-h] -m MESH_FILE_NAME -g GEOJSON_FILE_NAME
+                                     -o MASK_FILE_NAME
+                                     [-t MASK_TYPES [MASK_TYPES ...]]
+                                     [-c CHUNK_SIZE] [--show_progress]
+                                     [-s SUBDIVISION]
+                                     [--process_count PROCESS_COUNT]
+                                     [--multiprocessing_method MULTIPROCESSING_METHOD]
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      -m MESH_FILE_NAME, --mesh_file_name MESH_FILE_NAME
                             An MPAS mesh file
       -g GEOJSON_FILE_NAME, --geojson_file_name GEOJSON_FILE_NAME
                             An Geojson file containing mask regions

conda_package/docs/mesh_creation.rst

@@ -1,8 +1,8 @@
-.. _mesh_creation:
-
 .. |---| unicode:: U+2014  .. em dash, trimming surrounding whitespace
    :trim:
 
+.. _mesh_creation:
+
 *************
 Mesh Creation
 *************

conda_package/docs/mpas_to_xdmf.rst

@@ -26,12 +26,15 @@ The converter can be used via its command-line interface ``mpas_to_xdmf`` or as
 a Python library.
 
 .. note::
-   Special variable keys:
-     - ``allOnCells``: all variables with dimension ``nCells``
-     - ``allOnEdges``: all variables with dimension ``nEdges``
-     - ``allOnVertices``: all variables with dimension ``nVertices``
-   Extra dimensions (e.g., ``nVertLevels``) can be sliced using the ``-d``
-   CLI option or the ``extra_dims`` argument in Python.
+
+  Special variable keys:
+
+  - ``allOnCells``: all variables with dimension ``nCells``
+  - ``allOnEdges``: all variables with dimension ``nEdges``
+  - ``allOnVertices``: all variables with dimension ``nVertices``
+
+  Extra dimensions (e.g., ``nVertLevels``) can be sliced using the ``-d``
+  CLI option or the ``extra_dims`` argument in Python.
 
 Command-Line Arguments
 ----------------------

conda_package/docs/releasing.rst

@@ -17,13 +17,15 @@ Version Bump and Dependency Updates
      - ``conda_package/mpas_tools/__init__.py``
      - ``conda_package/recipe/meta.yaml``
 
-   - Make sure the version follows [semantic versioning](https://semver.org/).
+   - Make sure the version follows semantic versioning (see
+     https://semver.org/).
      For release candidates, use versions like ``1.3.0rc1`` (no ``v`` prefix).
 
 2. **Check and Update Dependencies**
 
    - Ensure that dependencies and their constraints are up-to-date and
      consistent in:
+
      - ``conda_package/recipe/meta.yaml`` (dependencies for the conda-forge
        release)
      - ``conda_package/pyproject.toml`` (dependencies for PyPI; used as a

conda_package/mpas_tools/viz/mpas_to_xdmf/mpas_to_xdmf.py

@@ -16,13 +16,15 @@
 Example Usage
 -------------
 Python:
+
     >>> from mpas_tools.viz.mpas_to_xdmf.mpas_to_xdmf import MpasToXdmf
     >>> converter = MpasToXdmf()
     >>> converter.load(mesh_filename="mesh.nc", time_series_filenames="output.*.nc",
     ...                variables=["temperature", "salinity"], xtime_var="xtime")
     >>> converter.convert_to_xdmf(out_dir="output_dir", extra_dims={"nVertLevels": [0, 1, 2]})
 
 Command line:
+
     $ mpas_to_xdmf -m mesh.nc -t output.*.nc -v temperature salinity -o output_dir -d nVertLevels=0:3
 
 See Also
@@ -92,8 +94,14 @@ def load(
         xtime_var=None,
     ):
         """
-        Load the MPAS mesh file and optionally combine it with time series
-        files into a single xarray Dataset.
+        Load the MPAS mesh file and optional time series.
+
+        Special keys for ``variables``:
+
+            - ``"allOnCells"`` - all variables with dimension ``"nCells"``
+            - ``"allOnEdges"`` - all variables with dimension ``"nEdges"``
+            - ``"allOnVertices"`` - all variables with dimension
+              ``"nVertices"``
 
         Parameters
         ----------
@@ -103,13 +111,10 @@ def load(
             List of NetCDF filenames or a wildcard string for time series
             files. If None, only the mesh file is used.
         variables : list of str, optional
-            List of variables to convert. Special keys:
-                - 'allOnCells': all variables with dimension 'nCells'
-                - 'allOnEdges': all variables with dimension 'nEdges'
-                - 'allOnVertices': all variables with dimension 'nVertices'
-            If None, all variables are included.
+            List of variables to convert. If None, all variables are included.
         xtime_var : str, optional
-            Name of the variable containing time information (e.g., 'xtime').
+            Name of the variable containing time information (e.g.,
+            ``"xtime"``).
         """
         self.ds_mesh, self.ds = _load_dataset(
             mesh_filename=mesh_filename,
@@ -128,8 +133,8 @@ def convert_to_xdmf(self, out_dir, extra_dims=None, quiet=False):
             Directory where XDMF and HDF5 files will be saved.
         extra_dims : dict, optional
             Dictionary mapping extra dimensions to their selected indices.
-            Example: {'nVertLevels': [0, 1, 2]}
-            If None, all indices are included.
+            Example - ``{'nVertLevels': [0, 1, 2]}``. If None, all indices are
+            included.
         quiet : bool, optional
             If True, suppress progress output.