UW-443 (#361)

ufs-community · Dec 13, 2023 · c04e051 · c04e051
1 parent 6ca09bb
commit c04e051
Show file tree

Hide file tree

Showing 26 changed files with 251 additions and 82 deletions.
diff --git a/docs/Makefile b/docs/Makefile
@@ -3,7 +3,7 @@ SOURCEDIR   = .
 SPHINXBUILD = sphinx-build
 SPHINXOPTS  = -n
 
-.PHONY: help
+.PHONY: help clean
 
 help:
 	$(SPHINXBUILD) -M help $(SOURCEDIR) $(BUILDDIR) $(SPHINXOPTS)

diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,17 @@
+To install into a development shell the dependencies needed to build docs:
+
+```
+source install-deps
+```
+
+To build docs:
+
+```
+make html
+```
+
+To view docs in browser, visit URL
+
+```
+file://<path-to-this-directory>/build/html/index.html
+```
diff --git a/docs/conf.py b/docs/conf.py
@@ -3,13 +3,20 @@
 import datetime as dt
 import json
 import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../src"))
 
 with open("../recipe/meta.json", "r", encoding="utf-8") as f:
     _metadata = json.loads(f.read())
 
+autodoc_mock_imports = ["f90nml", "jsonschema", "lxml"]
 copyright = str(dt.datetime.now().year)
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.intersphinx"]
 html_logo = os.path.join("static", "ufs.png")
 html_theme = "sphinx_rtd_theme"
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
+nitpick_ignore_regex = [("py:class", r"^uwtools\..*")]
 numfig = True
 numfig_format = {"figure": "Figure %s"}
 project = "Unified Workflow"

diff --git a/docs/install-deps b/docs/install-deps
@@ -0,0 +1 @@
+conda install -y $(python -c "import yaml; f=open('$(dirname ${BASH_SOURCE[0]})/environment.yml'); print(' '.join(yaml.safe_load(f)['dependencies']))")
diff --git a/docs/sections/contributor_guide/developer_setup.rst b/docs/sections/contributor_guide/developer_setup.rst
@@ -1,4 +1,4 @@
-.. include:: ../links.rst
+.. include:: links.rst
 
 ***************
 Developer Setup
@@ -7,8 +7,7 @@ Developer Setup
 Creating a ``bash`` development shell
 =====================================
 
-
-.. include:: ../reusable_text.rst
+.. include:: ../miniforge3_instructions.rst
 
 2. Install the `condev`_ package into the base environment.
 
@@ -18,17 +17,14 @@ Creating a ``bash`` development shell
 
 3. In a clone of the `workflow-tools repository`_, create the development shell.
 
-
    .. code:: sh
 
      cd /to/your/workflow-tools/clone
      make devshell
 
-
-
 If the above is successful, you will be in a ``workflow-tools`` development shell. See below for usage information. You may exit the shell with ``exit`` or ``ctrl-d``.
 
-Future ``make devshell`` invocations will be almost instantaneous, as the underlying virtual environment will already exist. In general, all source code changes will be immediately live in the development shell, subject to execution, test, etc. But some changes – especially to the contents of the ``recipe/`` directory, or to the ``src/setup.py`` module – may require recreation of the development shell. If you know this is needed, or when in doubt: 
+Future ``make devshell`` invocations will be almost instantaneous, as the underlying virtual environment will already exist. In general, all source code changes will be immediately live in the development shell, subject to execution, test, etc. But some changes – especially to the contents of the ``recipe/`` directory, or to the ``src/setup.py`` module – may require recreation of the development shell. If you know this is needed, or when in doubt:
 
     1. Exit the development shell, run ``conda env remove -n DEV-uwtools`` to remove the old environment.
     2. Run ``make devshell`` to recreate it.
@@ -41,19 +37,17 @@ If your development shell misses any functionality you’re used to in your main
      source ~/.bashrc
      EOF
 
-
 Using a ``bash`` development shell
 ==================================
 
 In an active development shell, the following ``make`` targets are available and act on all ``.py`` files under ``src/``:
 
-
 +---------------------+------------------------------------------------------------+
 | Command             |  Description                                               |
 +=====================+============================================================+
 | ``make format``     | Formats python code  with `black`_,                        |
 |                     | imports with `isort`_,                                     |
-|                     |                                                            |  
+|                     |                                                            |
 |                     | docstrings with `docformatter`_,                           |
 |                     | and ``.jsonschema`` documents with `jq`_                   |
 +---------------------+------------------------------------------------------------+
@@ -71,7 +65,6 @@ In an active development shell, the following ``make`` targets are available and
 |                     | Checks defined CLI scripts                                 |
 +---------------------+------------------------------------------------------------+
 
-
 Note that ``make format`` is never run automatically, to avoid reformatting under-development code in a way that might surprise the developer. A useful development idiom is to periodically run ``make format && make test`` to perform a full code-quality sweep through the code. An additional check is run by the CI for unformatted code, ``make format`` must be run, and then changes from ``make format`` must be committed before CI will pass.
 
 The ``make test`` command is also automatically executed when ``conda`` builds a ``uwtools`` package, so it is important to periodically run these tests during development and, crucially, before merging changes, to ensure that the tests will pass when CI builds the ``workflow-tools`` code.
@@ -86,7 +79,6 @@ The order of the targets above is intentional, and possibly useful:
 
 In addition to the ``make devshell`` command, other ``make`` targets are available for use *outside* a development shell, i.e. from the base conda environment (requires presence of the ``condev`` package):
 
-
 +------------------+-------------------------------------------------------+
 | Command          | Description                                           |
 +==================+=======================================================+
@@ -98,7 +90,6 @@ In addition to the ``make devshell`` command, other ``make`` targets are availab
 | ``make package`` | Builds a ``uwtools`` conda package                    |
 +------------------+-------------------------------------------------------+
 
-
 These targets work from the code in its current state in the clone. ``make env`` calls ``make package`` automatically to create a local package, then builds an environment based on the package.
 
 Building condev locally

diff --git a/docs/sections/contributor_guide/index.rst b/docs/sections/contributor_guide/index.rst
@@ -7,3 +7,4 @@ Contributor Guide
    developer_setup
    code_quality
    fork_pr_model
+   documentation
diff --git a/docs/sections/contributor_guide/links.rst b/docs/sections/contributor_guide/links.rst
@@ -0,0 +1 @@
+.. include:: ../links.rst
diff --git a/docs/sections/links.rst b/docs/sections/links.rst
@@ -1,18 +1,18 @@
 .. _Anaconda: https://anaconda.org
-.. _black: https://black.readthedocs.io/en/stable/ 
-.. _conda: https://docs.conda.io/en/latest/
+.. _Miniconda: https://docs.conda.io/en/latest/miniconda.html
+.. _Miniforge3: https://github.com/conda-forge/miniforge#download
+.. _Miniforge: https://github.com/conda-forge/miniforge
+.. _black: https://black.readthedocs.io/en/stable/
 .. _conda-forge: https://conda-forge.org/
-.. _condev: https://github.com/maddenp/condev
+.. _conda: https://docs.conda.io/en/latest/
 .. _condev demo: https://github.com/maddenp/condev/tree/main/demo
-.. _coverage: https://coverage.readthedocs.io/en/7.2.7/ 
-.. _docformatter: https://docformatter.readthedocs.io/en/stable/ 
+.. _condev: https://github.com/maddenp/condev
+.. _coverage: https://coverage.readthedocs.io/en/7.2.7/
+.. _docformatter: https://docformatter.readthedocs.io/en/stable/
 .. _isort: https://pycqa.github.io/isort/
-.. _jq: https://jqlang.github.io/jq/manual/v1.6/ 
-.. _Miniconda: https://docs.conda.io/en/latest/miniconda.html
-.. _Miniforge: https://github.com/conda-forge/miniforge
-.. _Miniforge3: https://github.com/conda-forge/miniforge#download
+.. _jq: https://jqlang.github.io/jq/manual/v1.6/
 .. _mypy: https://mypy.readthedocs.io/en/stable/
 .. _pylint: https://pylint.readthedocs.io/en/stable/
-.. _pytest: https://docs.pytest.org/en/stable/ 
+.. _pytest: https://docs.pytest.org/en/stable/
 .. _semantic versioning: https://semver.org/
 .. _workflow-tools repository: https://github.com/ufs-community/workflow-tools
diff --git a/docs/sections/Miniforge3_instructions.rst → docs/sections/miniforge3_instructions.rst b/docs/sections/Miniforge3_instructions.rst → docs/sections/miniforge3_instructions.rst
@@ -1,10 +1,11 @@
+.. include:: links.rst
+
 This recipe uses the ``aarch64`` (64-bit ARM) Miniforge for Linux, and installs into ``$HOME/conda``. Adjust as necessary for your target system.
- 
+
 1. Download, install, and activate the latest `Miniforge3`_ for your system. If an existing conda (Miniforge, Miniconda, Anaconda, etc.) installation is available and writable, you may activate that and skip this step and continue on to the next.
-
-
+
     .. code:: sh
- 
+
       wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-aarch64.sh
       bash Miniforge3-Linux-aarch64.sh -bfp ~/conda
       rm Miniforge3-Linux-aarch64.sh

diff --git a/docs/sections/user_guide/api/config.rst b/docs/sections/user_guide/api/config.rst
@@ -0,0 +1,6 @@
+**********************
+``uwtools.api.config``
+**********************
+
+.. automodule:: uwtools.api.config
+    :members:
diff --git a/docs/sections/user_guide/api/forecast.rst b/docs/sections/user_guide/api/forecast.rst
@@ -0,0 +1,6 @@
+************************
+``uwtools.api.forecast``
+************************
+
+.. automodule:: uwtools.api.forecast
+    :members:
diff --git a/docs/sections/user_guide/api/index.rst b/docs/sections/user_guide/api/index.rst
@@ -2,4 +2,9 @@
 API
 ***
 
-TBD
+.. toctree::
+   config
+   forecast
+   logging
+   rocoto
+   template
diff --git a/docs/sections/user_guide/api/logging.rst b/docs/sections/user_guide/api/logging.rst
@@ -0,0 +1,6 @@
+***********************
+``uwtools.api.logging``
+***********************
+
+.. automodule:: uwtools.api.logging
+    :members:
diff --git a/docs/sections/user_guide/api/rocoto.rst b/docs/sections/user_guide/api/rocoto.rst
@@ -0,0 +1,6 @@
+**********************
+``uwtools.api.rocoto``
+**********************
+
+.. automodule:: uwtools.api.rocoto
+    :members:
diff --git a/docs/sections/user_guide/api/template.rst b/docs/sections/user_guide/api/template.rst
@@ -0,0 +1,6 @@
+************************
+``uwtools.api.template``
+************************
+
+.. automodule:: uwtools.api.template
+    :members:
diff --git a/docs/sections/user_guide/installation.rst b/docs/sections/user_guide/installation.rst
@@ -1,56 +1,45 @@
-.. include:: ../links.rst
+.. include:: links.rst
 
 ************
 Installation
 ************
 
+-  If you are a **developer**, please visit the `Developer Setup <../contributor_guide/developer_setup.html>`_ section located in the `Contributor Guide <../contributor_guide/index.html>`_.
 
--  If you are a Developer, skip the User Installation and continue on to the `Developer Setup <../contributor_guide/developer_setup.html>`_ located in the Contributor Guide.
-
-The recommended installation mechanism uses the Python package and virtual-environment manager `conda`_. Specifically, these instructions detail the use of the minimal `Miniforge`_ variant of `Miniconda`_, built to use, by default, packages from the `conda-forge`_ project. 
+The recommended installation mechanism uses the Python package and virtual-environment manager `conda`_. Specifically, these instructions detail the use of the minimal `Miniforge`_ variant of `Miniconda`_, built to use, by default, packages from the `conda-forge`_ project.
 
 Users of the original Miniconda (or the `Anaconda`_ distribution) may need to add the flags ``-c conda-forge --override-channels`` to ``conda build``, ``conda create``, and ``conda install`` commands to specify the use of conda-forge packages.
 
-
 Using a fresh Miniforge installation
 ====================================
 
-.. include:: ../Miniforge3_instructions.rst
-
+.. include:: ../miniforge3_instructions.rst
 
 2. Install the ``conda-build`` and ``conda-verify`` packages into the base environment. If ``conda-build`` and ``conda-verify`` are already installed in the your installation’s base environment, you may skip this step.
 
-
    .. code:: sh
 
      conda install -y conda-build conda-verify
 
-
 3. In a clone of the `workflow-tools repository`_, build and install the ``uwtools`` package.
 
-
    .. code:: sh
 
      cd /to/your/workflow-tools/clone
      conda build recipe
      conda create -y -n uwtools -c local uwtools
 
-
 4. Activate the ``uwtools`` environment.
 
-
    .. code:: sh
 
      conda activate uwtools
 
-
 In future shells, you can activate and use this environment with:
 
-
    .. code:: sh
 
      source ~/conda/etc/profile.d/conda.sh
      conda activate uwtools
 
-
 Note that the ``uwtools`` package’s actual name will contain version and build information, e.g. ``uwtools-0.1.0-py_0``. The ``conda create`` command will find and use the most recent `semantic versioning`_ - compliant package name given the base name ``uwtools``. It could also be explicitly specified as ``uwtools=0.1.0=py_0``.
diff --git a/docs/sections/user_guide/links.rst b/docs/sections/user_guide/links.rst
@@ -0,0 +1 @@
+.. include:: ../links.rst