Update documentation

Author: github-actions[bot]

master/.doctrees/cime.doctree

@@ -8,7 +8,7 @@ sync with `CIME <https://github.com/ESMCI/cime>`_, which provides infrastructure
 and utilities for Earth System Models such at E3SM.  Currently, we sync only
 those constants given numerical values in CIME, not those that are derivied
 from other constants.  Constants are checked against their values on CIME's
-master branch during tests of the conda build.
+master branch during tests of the rattler-build package build.
 
 Some of the constants most likely to be useful in MPAS-Tools, COMPASS and other
 related projects are:

master/.doctrees/environment.pickle

@@ -60,7 +60,7 @@ Entry Points
 
 The best way to add new "scripts" to the package is to add a function without
 any arguments somewhere in the package, and then to add it as an "entry point"
-both in ``conda_package/pyproject.toml`` and ``conda_package/recipe/meta.yaml``.
+both in ``conda_package/pyproject.toml`` and ``conda_package/recipe/recipe.yaml``.
 
 As an example, the entry point ``planar_hex`` is defined in ``pyproject.toml`` as:
 
@@ -71,7 +71,7 @@ As an example, the entry point ``planar_hex`` is defined in ``pyproject.toml`` a
   planar_hex = "mpas_tools.planar_hex:main"
   ...
 
-and in ``meta.yaml`` as:
+and in ``recipe.yaml`` as:
 
 .. code-block::
 
@@ -108,11 +108,11 @@ Dependencies
 ============
 
 If you changes introduce new dependencies, these need to be added to both
-the recipe for the conda package in ``conda_package/recipe/meta.yaml`` and
+the recipe for the conda package in ``conda_package/recipe/recipe.yaml`` and
 to the text file describing the development environment,
-``conda_package/dev-spec.txt``.
+``conda_package/dev-spec.txt`` and to ``conda_package/pixi.toml``.
 
-In ``meta.yaml``, add these changes in alphabetical order to the ``run``
+In ``recipe.yaml``, add these changes in alphabetical order to the ``run``
 section of ``requirements``:
 
 .. code-block:: yaml
@@ -127,8 +127,9 @@ section of ``requirements``:
 These requirements *must* be on the ``conda-forge`` anaconda channel.  If you
 need help with this, please contact the developers.
 
-Add the new dependencies in alphabetical order to ``dev-speck.txt``
-under the ``# Base`` comment:
+Add the new dependencies in alphabetical order to ``dev-spec.txt``
+under the ``# Base`` comment and keep ``conda_package/pixi.toml`` in sync
+with the same constraints:
 
 .. code-block:: none
 
@@ -155,7 +156,7 @@ updated in 3 places.  First, in ``conda_package/mpas_tools/__init__.py``:
 Increment ``__version_info__`` (major, minor or micro version, depending on
 what makes sense).
 
-Second, the version in the conda recipe (``conda_package/recipe/meta.yaml``)
+Second, the version in the conda recipe (``conda_package/recipe/recipe.yaml``)
 needs to match:
 
 .. code-block::

master/.doctrees/making_changes.doctree

@@ -15,7 +15,7 @@ Version Bump and Dependency Updates
    - Open a pull request (PR) to update the version number in the following
      two files:
      - ``conda_package/mpas_tools/__init__.py``
-     - ``conda_package/recipe/meta.yaml``
+     - ``conda_package/recipe/recipe.yaml``
 
    - Make sure the version follows semantic versioning (see
      https://semver.org/).
@@ -26,18 +26,21 @@ Version Bump and Dependency Updates
    - Ensure that dependencies and their constraints are up-to-date and
      consistent in:
 
-     - ``conda_package/recipe/meta.yaml`` (dependencies for the conda-forge
+     - ``conda_package/recipe/recipe.yaml`` (dependencies for the conda-forge
        release)
      - ``conda_package/pyproject.toml`` (dependencies for PyPI; used as a
        sanity check)
      - ``conda_package/dev-spec.txt`` (development dependencies; should be a
        superset of those for the conda-forge release)
+     - ``conda_package/pixi.toml`` (pixi development dependencies; should
+       match ``dev-spec.txt``)
 
-   - The dependencies in ``meta.yaml`` are the ones that will be used for the
+   - The dependencies in ``recipe.yaml`` are the ones that will be used for the
      released package on conda-forge. The dependencies in ``pyproject.toml``
      are for PyPI and should be kept in sync as much as possible but are only
      there as a sanity check when we run ```pip check``. The ``dev-spec.txt``
-     file should include all dependencies needed for development and testing.
+     file should include all dependencies needed for development and testing,
+     and ``pixi.toml`` should remain equivalent for pixi users.
 
    - Review and update dependency versions and constraints as needed.
 
@@ -91,7 +94,7 @@ Tagging and Publishing a Release Candidate
 
          shasum -a 256 <version>.tar.gz
 
-   - In the ``meta.yaml`` of the feedstock recipe:
+  - In the ``recipe.yaml`` of the feedstock recipe:
      - Set ``{% set version = "<version>" %}``
      - Set the new ``sha256`` value
      - Update dependencies if needed

master/.doctrees/releasing.doctree

@@ -6,23 +6,94 @@ Testing Changes to mpas_tools
 
 Here, we describe the workflow for creating a development conda environment
 that points to ``mpas_tools`` in a branch from a local clone of the repo.
-This approach works both for calling functions from the package within a python
-script or another python package and for calling the "entry points"
-(command-line tools; see :ref:`dev_making_changes`).
+The preferred workflow is to build and install the package locally with
+``rattler-build`` from within a pixi environment.
 
-Basic instructions on how to install `Miniconda <https://docs.conda.io/en/latest/miniconda.html>`_
-are beyond the scope of this documentation. Make sure the conda-forge channel
-is added and that channel priority is "strict", meaning packages will
-definitely come from conda-forge if they are available there.
+.. _dev_local_rattler_build:
+
+Building and Installing Locally with rattler-build
+***************************************************
+
+This is the recommended method, and it is required if you are modifying
+compiled C++ or Fortran tools.
+
+Use the pixi environment in ``conda_package/pixi.toml`` to run the build
+command:
+
+.. code-block:: bash
+
+    cd conda_package
+    pixi install
+    pixi shell
+    rattler-build build -m ci/linux_64_python3.14.____cpython.yaml -r recipe/ --output-dir ../output
+
+This writes package artifacts to ``output/`` in the repository root.
+
+To install the locally built package into the pixi environment, add the local
+build output as a channel and then add ``mpas_tools`` from that channel:
+
+.. code-block:: bash
+
+    cd conda_package
+    pixi workspace channel add "file://$PWD/../output"
+    pixi add --platform linux-64 "mpas_tools [channel='file://$PWD/../output']"
+
+.. warning::
+
+    The commands above modify ``pixi.toml`` (and possibly ``pixi.lock``).
+    These are local development changes only and should **not** be committed.
+    Before opening a PR, reset those files to the repository state.
+
+On macOS, use ``--platform osx-64`` instead.  If your workspace includes both
+``linux-64`` and ``osx-64`` in ``pixi.toml``, pixi may try to solve both
+platforms during dependency updates.  In that case, build local artifacts for
+both platforms (with corresponding CI recipe files) or add the local package
+for only the platform you built.
+
+If you want to return to using only published channels afterward, you can
+remove the local channel from ``pixi.toml``.
+
+Quick-and-Dirty Alternative: Pixi Editable Install
+**************************************************
+
+If you are only making Python-level changes and do not need to rebuild the
+compiled C++/Fortran tools, you can use editable installation in pixi:
+
+.. code-block:: bash
+
+    cd conda_package
+    pixi install
+    pixi shell
+    pixi run install-editable
+
+Then run tools within the pixi shell (for example ``pytest``).
+
+.. important::
+
+    Editable installation updates Python code but does **not** rebuild compiled
+    C++ and Fortran command-line tools.
+
+    A useful hybrid workflow is to install the latest release conda package
+    first (to get compiled tools), then install your branch in editable mode on
+    top for Python development.
+
+Legacy Method: Conda Editable Install
+*************************************
+
+This workflow is kept for compatibility but is no longer the preferred method.
+
+Basic instructions on how to install
+`Miniconda <https://docs.conda.io/en/latest/miniconda.html>`_ are beyond the
+scope of this documentation. Make sure the conda-forge channel is added and
+that channel priority is "strict":
 
 .. code-block:: bash
 
     conda config --add channels conda-forge
     conda config --set channel_priority strict
 
-To make a conda environment and install the current `mpas_tools` in a way that
-it will be used out of the repo directly (i.e. it will notice changes as you
-make them in your branch), run:
+Then create and activate a development environment from ``dev-spec.txt`` and
+install in editable mode:
 
 .. code-block:: bash
 
@@ -31,14 +102,8 @@ make them in your branch), run:
     conda activate mpas_tools_dev
     python -m pip install --no-deps --no-build-isolation -e .
 
-You should now find that ``mpas_tools`` can be imported in python codes and the
-various scripts and entry points are available in the path.
-
-If you have already created the ``mpas_tools_dev`` environment, it may be best
-to remove it (see below) and create it again.
-
 Removing the test environment
-*****************************
+-----------------------------
 
 If you're done with testing, you can remove the test environment
 

master/.doctrees/testing_changes.doctree

@@ -131,7 +131,7 @@
 and utilities for Earth System Models such at E3SM.  Currently, we sync only
 those constants given numerical values in CIME, not those that are derivied
 from other constants.  Constants are checked against their values on CIME’s
-master branch during tests of the conda build.</p>
+master branch during tests of the rattler-build package build.</p>
 <p>Some of the constants most likely to be useful in MPAS-Tools, COMPASS and other
 related projects are:</p>
 <ul class="simple">