Clean up docs and docstrings

Fix various formatting errors causing warnings in docs build.

Author: xylar

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

@@ -92,8 +92,7 @@ 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.
 
         Parameters
         ----------
@@ -104,12 +103,16 @@ def load(
             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'
+
+            - ``"allOnCells"``: all variables with dimension ``"nCells"``
+            - ``"allOnEdges"``: all variables with dimension ``"nEdges"``
+            - ``"allOnVertices"``: all variables with dimension
+              ``"nVertices"``
+
             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,