Merge pull request #1042 from xylar/fix-docs

Several fixes to the docs

.github/pull_request_template.md

@@ -4,15 +4,15 @@ Please add a description of what is accomplished in the PR here at the top:
 -->
 
 <!--
-Below are a few things we ask you or your reviewers to kindly check. 
+Below are a few things we ask you or your reviewers to kindly check.
 ***Remove checks that are not relevant by deleting the line(s) below.***
 -->
 Checklist
 * [ ] User's Guide has been updated
 * [ ] If this PR adds a new analysis task, it has also been added to the user's guide
 * [ ] Developer's Guide has been updated
 * [ ] API documentation in the Developer's Guide (`api.rst`) has any new or modified class, method and/or functions listed
-* [ ] Documentation has been [built locally](https://mpas-dev.github.io/MPAS-Analysis/latest/users_guide/quick_start.html#generating-documentation) and changes look as expected
+* [ ] Documentation has been [built locally](https://mpas-dev.github.io/MPAS-Analysis/develop/users_guide/quick_start.html#generating-documentation) and changes look as expected
 * [ ] `Testing` comment in the PR documents testing used to verify the changes
 
 <!--

docs/tutorials/dev_add_task.rst

@@ -9,6 +9,12 @@ analysis task that is as close as possible to the new analysis, and to copy
 that existing task as a template for the new task.  That is the strategy we
 will demonstrate here.
 
+.. note::
+
+   The changes will not be broadly available until the next MPAS-Analysis
+   release and to the broader E3SM community after the next
+   `E3SM-Unified <https://github.com/E3SM-Project/e3sm-unified>`_ release.
+
 To provide a real example, we will show how we copy and modify an analysis
 task used to compute the anomaly in ocean heat content
 (:py:class:`~mpas_analysis.ocean.ClimatologyMapOHCAnomaly`) to instead compute
@@ -22,6 +28,22 @@ notebooks include hard-coded paths and are otherwise not easily applied to new
 simulations without considerable effort. This is the motivation for adapting
 the code to MPAS-Analysis.
 
+
+.. note::
+
+   If one just wishes to add a new field that already exists in MPAS-Ocean or
+   MPAS-Seaice output, only a few of the steps below are necessary:
+
+   1. Follow step 1 to set up an ```mpas_dev``` environment.
+   2. Copy an existing `ocean <https://github.com/MPAS-Dev/MPAS-Analysis/tree/develop/mpas_analysis/ocean>`_
+      or `sea_ice <https://github.com/MPAS-Dev/MPAS-Analysis/tree/develop/mpas_analysis/sea_ice>`_
+      python module to a new name and edit it as needed for the new fields.
+   3. Follow step 6 to add config options
+   4. Follow step 7 to add the task to the list of tasks known to
+      MPAS-Analysis
+   5. Follow step 8 to update Analysis Tasks in the user's guide and
+      ``api.rst`` in the developer's guide to include the new analysis task.
+
 1. Getting started
 ------------------
 
@@ -31,6 +53,14 @@ cloning it onto the machine(s) where you will do your development, making
 a worktree for the feature you will develop, creating a conda environment for
 testing your new MPAS-Analysis development, and running MPAS-Analysis.
 
+.. note::
+
+   Make sure you follow the tutorial for developers, not for users, since the
+   tutorial for users installs the latest release of MPAS-Analysis, which you
+   cannot modify. Similarly, changes must be tested in your own development
+   environment (often called ``mpas_dev``) rather than the in a shared
+   environment like `E3SM-Unified <https://github.com/E3SM-Project/e3sm-unified>`_.
+
 Then, please follow the :ref:`tutorial_understand_a_task`.  This will give
 you a tour of the :py:class:`~mpas_analysis.ocean.ClimatologyMapOHCAnomaly`
 analysis task that we will use as a starting point for developing a new task.
@@ -513,12 +543,12 @@ task to the new name:
     cd ../add_climatology_map_bsf
     cp mpas_analysis/ocean/climatology_map_ohc_anomaly.py mpas_analysis/ocean/climatology_map_bsf.py
 
-Then, I'll open this new worktree in PyCharm.  (You can, of course, use
+Then, I'll open this new worktree in VS Code.  (You can, of course, use
 whatever editor you like.)
 
 .. code-block:: bash
 
-    pycharm-community .
+    code .
 
 I'll create or recreate my ``mpas_dev`` environment as in
 :ref:`tutorial_dev_getting_started`, and then make sure to at least do:
@@ -528,6 +558,9 @@ I'll create or recreate my ``mpas_dev`` environment as in
     conda activate mpas_dev
     python -m pip install --no-deps --no-build-isolation -e .
 
+This last command installs the ``mpas_analysis`` package into the conda
+environment.
+
 4.1 ``ClimatologyMapBSF`` class
 -------------------------------
 
@@ -1092,7 +1125,32 @@ A quick way to check if the task has been added correctly is to run:
 You should see the new task in the list of tasks.
 
 
-8. The full code for posterity
+8. Adding documentation
+-----------------------
+
+You need to add the task to the documentation.  The easiest way to do this
+is to copy an existing task's documentation (the more similar, the better) in
+the `tasks <https://github.com/MPAS-Dev/MPAS-Analysis/tree/develop/docs/users_guide/tasks>`_
+directory and then modify it.
+
+You also need to add the tasks class and public methods to the
+`api.rst <https://github.com/MPAS-Dev/MPAS-Analysis/blob/develop/docs/developers_guide/api.rst>`_
+in the developer's guide.  Again, the easiest approach is to copy the section
+for a similar task and modify as needed.
+
+With the ``mpas_dev`` environment activated, you can run:
+
+.. code-block:: bash
+
+    cd docs
+    make clean html
+
+to build the docs locally in the ``_build/html`` subdirectory.  When generating
+documentation on HPC machines, you will want to copy the html output to the
+public web space to view it, or if the web portal is being cranky, scp it to
+your local machine.
+
+9. The full code for posterity
 ------------------------------
 
 Since the ``ClimatologyMapBSF`` analysis task is not in MPAS-Analysis yet and

docs/tutorials/dev_getting_started.rst

@@ -10,6 +10,12 @@ development, and creating a conda environment that includes the
 ``mpas_analysis`` package and all of its dependencies, installed in a mode
 appropriate for development.
 
+.. warning::
+
+   Beware of hyphens and underscores. The conda package name and some
+   environment names use a hyphen (``mpas-analysis``). The python package and
+   the command name use an underscore (``mpas_analysis``).
+
 1. Getting started on GitHub
 ----------------------------
 
@@ -141,28 +147,27 @@ MPAS-Analysis relies on several packages that are only available as conda
 packages from the ``conda-forge`` channel.  The first step for running
 MPAS-Analysis is to create a conda environment with all the needed packages.
 
-4.1 Installing Mambaforge
+4.1 Installing Miniforge3
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you have not yet installed Anaconda, Miniconda or Mambaforge, you will need
+If you have not yet installed Anaconda, Miniconda or Miniforge, you will need
 to begin there.  The concept behind Anaconda is that just about everything you
 would need for a typical python workflow is included.  The concept behind
-Miniconda and Mambaforge is that you create different environments for
+Miniconda and Miniforge is that you create different environments for
 different purposes.  This allows for greater flexibility and tends to lead to
 fewer conflicts between incompatible packages, particularly when using a
 channel other than the ``defaults`` supplied by Anaconda.  Since we will use
-the ``conda-forge`` channel and the ``mamba`` tools to speed up installation,
-the Mambaforge approach is strongly recommended.  The main advantage of
-Mambaforge over Miniconda is that it automatically takes care of a few steps
-that we otherwise need to do manually.
+the ``conda-forge`` channel, the Miniforge3 approach is strongly recommended.
+The main advantage of Miniforge3 over Miniconda is that it automatically takes
+care of a few steps that we otherwise need to do manually.
 
 First download the
-`Mambaforge installer <https://github.com/conda-forge/miniforge#mambaforge>`_
+`Miniforge3 installer <https://github.com/conda-forge/miniforge?tab=readme-ov-file#miniforge3>`_
 for your operating system, then run it:
 
 .. code-block:: bash
 
-   $ /bin/bash Mambaforge-Linux-x86_64.sh
+   $ /bin/bash Miniforge3-Linux-x86_64.sh
 
 .. note::
 
@@ -181,56 +186,56 @@ You will be asked to agree to the terms and conditions. Type ``yes`` to
 continue.
 
 You will be prompted with a location to install. In this tutorial, we assume
-that Mambaforge is installed in the default location, ``~/mambaforge``.  If
-you are using Miniconda or chose to install Mambaforge somewhere else, just
+that Miniforge3 is installed in the default location, ``~/miniforge3``.  If
+you are using Miniconda or chose to install Miniforge3 somewhere else, just
 make sure to make the appropriate substitution whenever you see a reference to
 this path below.
 
 .. note::
 
     On some HPC machines (particularly at LANL Institutional Computing and
     NERSC) the space in your home directory is quite limited.  You may want to
-    install Mambaforge in an alternative location to avoid running out of
+    install Miniforge3 in an alternative location to avoid running out of
     space.
 
 You will see prompt like this:
 
 .. code-block::
 
-    Do you wish the installer to initialize Mambaforge
+    Do you wish the installer to initialize Miniforge3
     by running conda init? [yes|no]
     [no] >>>
 
 You may wish to skip the step (answer ``no``) if you are working on a system
 where you will also be using other conda environments, most notably
-E3SM-Unified (which has its own Miniconda installation).  If you do not run
+E3SM-Unified (which has its own Miniforge3 installation).  If you do not run
 conda init, you have to manually activate ``conda`` whenever you need it.
 For ``bash`` and similar shells, this is:
 
 .. code-block:: bash
 
-   $ source ~/mambaforge/etc/profile.d/conda.sh
+   $ source ~/miniforge3/etc/profile.d/conda.sh
    $ conda activate
 
 If you use ``csh``, ``tcsh`` or related shells, this becomes:
 
 .. code-block:: csh
 
-   > source ~/mambaforge/etc/profile.d/conda.csh
+   > source ~/miniforge3/etc/profile.d/conda.csh
    > conda activate
 
 You may wish to create an alias in your ``.bashrc`` or ``.cshrc`` to make
 this easier.  For example:
 
 .. code-block:: bash
 
-   alias init_conda="source ~/mambaforge/etc/profile.d/conda.sh; conda activate"
+   alias init_conda="source ~/miniforge3/etc/profile.d/conda.sh; conda activate"
 
 
 4.2 One-time Miniconda setup
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you installed Miniconda, rather than Mambaforge, you will need to add the
+If you installed Miniconda, rather than Miniforge3, you will need to add the
 `conda-forge channel <https://conda-forge.org/>`_ and make sure it always takes
 precedence for packages available on that channel:
 
@@ -239,13 +244,7 @@ precedence for packages available on that channel:
    $ conda config --add channels conda-forge
    $ conda config --set channel_priority strict
 
-Then, you will need to install the ``mamba`` package:
-
-.. code-block:: bash
-
-   $ conda install -y mamba
-
-If you installed Mambaforge, these steps will happen automatically.
+If you installed Miniforge3, these steps will happen automatically.
 
 4.3 Create a development environment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -256,7 +255,7 @@ where you are doing your development:
 
 .. code-block:: bash
 
-   $ mamba create -y -n mpas_dev --file dev-spec.txt "esmf=*=nompi_*"
+   $ conda create -y -n mpas_dev --file dev-spec.txt
 
 The last argument is only needed on HPC machines because the conda version of
 MPI doesn't work properly on these machines.  You can omit it if you're
@@ -274,14 +273,15 @@ In this mode, any edits you make to the code in the worktree will be available
 in the conda environment.  If you run ``mpas_analysis`` on the command line,
 it will know about the changes.
 
-.. note::
-
-    If you add or remove files in the code, you will need to re-install
-    MPAS-Analysis in the conda environment by rerunning
+This command only needs to be done once after the ``mpas_dev`` environment is
+built if you are not using worktrees.
 
-    .. code-block:: bash
+.. note::
 
-       python -m pip install --no-deps --no-build-isolation -e .
+   If you do use worktrees, rerun the ``python -m pip install ...`` command
+   each time you switch to developing a new branch, since otherwise the
+   version of ``mpas_analysis`` in the ``mpas_dev`` environment will be the
+   one you were developing previously.
 
 .. _tutorial_dev_get_started_activ_env:
 
@@ -293,17 +293,17 @@ environment, you will need to run either for ``bash``:
 
 .. code-block:: bash
 
-   $ source ~/mambaforge/etc/profile.d/conda.sh
+   $ source ~/miniforge3/etc/profile.d/conda.sh
    $ conda activate mpas_dev
 
 or for ``csh``:
 
 .. code-block:: csh
 
-   > source ~/mambaforge/etc/profile.d/conda.csh
+   > source ~/miniforge3/etc/profile.d/conda.csh
    > conda activate mpas_dev
 
-You can skip the ``source`` command if you chose to initialize Mambaforge or
+You can skip the ``source`` command if you chose to initialize Miniforge3 or
 Miniconda3 so it loads automatically.  You can also use the ``init_conda``
 alias for this step if you defined one.
 
@@ -328,11 +328,12 @@ using.
 
 You may, of course, edit the MPAS-Analysis code using whatever tool you like.
 I strongly recommend editing on your laptop and using
-`PyCharm community edition <https://www.jetbrains.com/pycharm/download/>`_
-to do the editing.  PyCharm provides many features including flagging
-deviations from preferred coding style guidelines known as
-`PEP8 <https://peps.python.org/pep-0008/>`_ and syntax error detection using
-the ``mpas_dev`` conda environment you created.
+`VS Code <https://code.visualstudio.com/>`_ to do the editing.  VS Code lets
+you edit code `remotely over ssh <https://code.visualstudio.com/docs/remote/ssh>`_
+(i.e. edit code on your laptop that lives on HPC) and provides many plugins
+that can be used to lint and debug your code on the fly.  This helps ensure
+that code follows the preferred coding style guidelines known as
+`PEP8 <https://peps.python.org/pep-0008/>`_.
 
 6. Running MPAS-Analysis on a laptop
 ------------------------------------
@@ -343,6 +344,13 @@ need to follow steps 2-6 of the :ref:`tutorial_getting_started` tutorial.
 7. Running MPAS-Analysis on an E3SM supported machine
 -----------------------------------------------------
 
+.. warning::
+
+   Run ``mpas_analysis`` on a compute node, not on an HPC login nodes (front
+   ends), because it uses too many resources to be safely run on a login node.
+   When using a compute node interactively, activate the ``mpas_dev``
+   environment, even if it was activated on the login node. Be sure to
+
 7.1 Configuring MPAS-Analysis
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -431,6 +439,16 @@ following:
     # serial but with a command)
     mapParallelExec = None
 
+If you find that new jobs are being lanuched for ncremap tasks, set:
+
+.. code-block:: ini
+    [execute]
+
+    ...
+    # "None" if ncremap should perform remapping without a command, or "srun"
+    # possibly with some flags if it should be run with that command
+    ncremapParallelExec = None
+
 If you are running into trouble with MPAS-Analysis, such as running out of
 memory, you may want to explore other config options from this section.
 

docs/tutorials/dev_understand_a_task.rst

@@ -132,7 +132,7 @@ Guide.
 
 It will be useful to open the following links in your browser to have a look
 at the code directly:
-`ClimatologyMapOHCAnomaly <https://github.com/xylar/MPAS-Analysis/blob/add_developer_task_tutorial/mpas_analysis/ocean/climatology_map_ohc_anomaly.py>`_
+`ClimatologyMapOHCAnomaly <https://github.com/MPAS-Dev/MPAS-Analysis/blob/main/mpas_analysis/ocean/climatology_map_ohc_anomaly.py>`_
 
 ..
    To do: switch the previous URL to https://github.com/MPAS-Dev/MPAS-Analysis/blob/develop