Document releasing conda package and more

README.md

@@ -7,9 +7,11 @@ should live in it's own directory.
 
 ## Documentation
 
-The latest documentation for the conda package `mpas-tools` can be found here:
+The latest documentation for the conda package `mpas_tools` can be found here:
 
 [http://mpas-dev.github.io/MPAS-Tools/master/](http://mpas-dev.github.io/MPAS-Tools/master/)
 
 Many tools are not in the conda package, and documentation (sometimes fairly
 limited) is available at the beginning of each script.
+
+**Note**: as of Sep 2025, [@xylar](https://github.com/xylar/) who has been the main maintainer of the conda package will no longer be working on the project. As a result updates to the `mpas_tools` conda package may be limited after that date.

conda_package/docs/config.rst

@@ -28,11 +28,48 @@ default behavior.  In some cases, you would like the code to add the config
 options if the config file exists and do nothing if it does not
 (``exception=False``).
 
-Ihe ``MpasConfigParser`` class also includes methods for adding a user
+The ``MpasConfigParser`` class also includes methods for adding a user
 config file, :py:meth:`mpas_tools.config.MpasConfigParser.add_user_config()`,
 and other config files by file name,
 :py:meth:`mpas_tools.config.MpasConfigParser.add_from_file()`.
 
+.. note::
+    The ``MpasConfigParser`` class also provides methods for combining config
+    files, listing contributing files, and merging config parsers:
+
+    +----------------------+---------------------------------------------------+
+    | Method               | Purpose                                           |
+    +======================+===================================================+
+    | add_from_file        | Add a config file by filename                     |
+    +----------------------+---------------------------------------------------+
+    | add_user_config      | Add a user config file (highest precedence)       |
+    +----------------------+---------------------------------------------------+
+    | add_from_package     | Add a config file from a Python package           |
+    +----------------------+---------------------------------------------------+
+    | get, getint, ...     | Retrieve config values                            |
+    +----------------------+---------------------------------------------------+
+    | getlist, getexpression | Retrieve values as lists or Python expressions  |
+    +----------------------+---------------------------------------------------+
+    | set                  | Set a config value, with optional comment         |
+    +----------------------+---------------------------------------------------+
+    | copy                 | Deep copy the config parser                       |
+    +----------------------+---------------------------------------------------+
+    | append, prepend      | Merge another config parser (priority control)    |
+    +----------------------+---------------------------------------------------+
+    | list_files           | List all contributing config files                |
+    +----------------------+---------------------------------------------------+
+
+Example usage
+-------------
+
+.. code-block:: python
+
+    from mpas_tools.config import MpasConfigParser
+    config = MpasConfigParser()
+    config.add_from_file('defaults.cfg')
+    config.add_user_config('user.cfg')
+    value = config.get('section', 'option')
+
 The :py:meth:`mpas_tools.config.MpasConfigParser.copy()` method can be used to
 make a deep copy of the config parser.  This is useful in cases where config
 options should be added or modified without affecting the original config
@@ -90,4 +127,3 @@ The comments can be any number of lines.
 
     Inline comments (after a config option on the same line) are not allowed
     and will be parsed as part of the config option itself.
-

conda_package/docs/index.rst

@@ -8,17 +8,18 @@ MPAS-Tools
 MPAS-Tools includes a python package, compiled Fortran, C and C++ tools, and
 scripts for supporting initialization, visualization and analysis of Model for
 Prediction Across Scales (MPAS) components.  These tools are used by the
-`COMPASS <https://github.com/MPAS-Dev/MPAS-Model/tree/master/testing_and_setup/compass>`_
-(Configuring of MPAS Setups) framework within
-`MPAS-Model <https://github.com/MPAS-Dev/MPAS-Model>`_ used to create
-ocean and land-ice test cases,
-the `MPAS-Analysis <https://github.com/MPAS-Dev/MPAS-Analysis>`_ package for
-analyzing simulations, and in other MPAS-related workflows.
+`Polaris <https://github.com/E3SM-Porject/polaris>`_ and
+`Compass <https://github.com/MPAS-Dev/compass>`_ packages used to create ocean,
+sea-ice, and land-ice test cases; the
+`MPAS-Analysis <https://github.com/MPAS-Dev/MPAS-Analysis>`_ package for
+analyzing simulations; and in other MPAS-related workflows.
 
 .. toctree::
    :caption: User's Guide
    :maxdepth: 2
 
+   quick_start
+
    mesh_creation
    mesh_conversion
    interpolation
@@ -78,6 +79,7 @@ analyzing simulations, and in other MPAS-related workflows.
    making_changes
    testing_changes
    building_docs
+   releasing
 
    api
 

conda_package/docs/interpolation.rst

@@ -9,12 +9,16 @@ Interpolation
 
 Previously, various tools in this package used ``scipy`` for interpolation.
 However, the interpolation routines in ``scipy`` are not well suited to
-interpolation from regular grids to MPAS meshes---they are slow and very memory
+interpolation from regular grids to MPAS meshes—they are slow and very memory
 intensive, particularly for large meshes.
 
-For bilinear interpolation from a tensor lon/lat grid to an MPAS mesh, it will
-be faster to use the function
-:py:func:`mpas_tools.mesh.interpolation.interp_bilin()`
+For bilinear interpolation from a tensor (regular) lon/lat grid to an MPAS
+mesh, it is much faster and more memory-efficient to use the function
+:py:func:`mpas_tools.mesh.interpolation.interp_bilin()`.
+This function is specifically designed for interpolating from a regular grid
+(e.g., longitude/latitude) to the unstructured cell centers of an MPAS mesh,
+and should be preferred over generic `scipy` routines for this use case.
+
 Here is an example where we define cell width for an EC mesh (see
 :ref:`ec_mesh`), read in longitude and latitude from an MPAS mesh, and
 interpolate the cell widths to cell centers on the MPAS mesh.
@@ -46,3 +50,9 @@ interpolate the cell widths to cell centers on the MPAS mesh.
     latCell = np.rad2deg(latCell)
 
     cellWidthOnMpas = interp_bilin(lon, lat, cellWidth, lonCell, latCell)
+
+.. note::
+    - All cell center coordinates must be within the bounds of the input grid.
+    - No extrapolation is performed.
+    - For geographic data, use degrees for longitude/latitude to avoid
+      round-off issues.