Add documentation for zppy-interfaces

.github/workflows/build_workflow.yml

@@ -109,75 +109,79 @@ jobs:
           pytest tests/unit/global_time_series/test_*.py
 
   # If the branch updates documentation, then the docs will need to be updated.
-  # publish-docs:
-  #   if: ${{ github.event_name == 'push' }}
-  #   runs-on: ubuntu-latest
-  #   defaults:
-  #     run:
-  #       shell: bash -l {0}
-  #   timeout-minutes: 10 # Increased timeout for docs
-  #   steps:
-  #     - uses: actions/checkout@v2
-  #       with:
-  #         persist-credentials: false
-  #         fetch-depth: 0
-
-  #     - name: Cache Conda
-  #       uses: actions/cache@v3
-  #       env:
-  #         CACHE_NUMBER: 1 # Match the build job cache number
-  #       with:
-  #         path: ~/conda_pkgs_dir
-  #         key: ${{ runner.os }}-conda-${{ env.CACHE_NUMBER }}-${{
-  #           hashFiles('conda/dev.yml') }}-docs
-
-  #     - name: Build Conda Environment
-  #       uses: conda-incubator/setup-miniconda@v3
-  #       with:
-  #         activate-environment: zppy_interfaces_dev
-  #         miniforge-variant: Miniforge3
-  #         miniforge-version: latest
-  #         environment-file: conda/dev.yml
-  #         channel-priority: strict
-  #         auto-update-conda: true
-  #         python-version: "3.13" # Use stable Python version for docs
-
-  #     - if: ${{ needs.check-jobs-to-skip.outputs.should_skip != 'true' }}
-  #       name: Show Conda Environment Info
-  #       run: |
-  #         conda config --set anaconda_upload no
-  #         conda info
-  #         conda list
-
-  #     - name: Install `zppy-interfaces` Package
-  #       run: pip install .
-
-  #     # sphinx-multiversion allows for version docs.
-  #     - name: Build Sphinx Docs
-  #       run: |
-  #         cd docs
-  #         sphinx-multiversion source _build/html
-
-  #     - name: Copy Docs and Commit
-  #       run: |
-  #         # gh-pages branch must already exist
-  #         git clone https://github.com/E3SM-Project/zppy-interfaces.git --branch gh-pages --single-branch gh-pages
-
-  #         # Only replace main docs with latest changes. Docs for tags should be untouched.
-  #         cd gh-pages
-  #         rm -r _build/html/main
-  #         cp -r ../docs/_build/html/main _build/html/main
-  #         git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
-  #         git config --local user.name "github-actions[bot]"
-
-  #         # The below command will fail if no changes were present, so we ignore it
-  #         git add .
-  #         git commit -m "Update documentation" -a || true
-
-  #     - name: Push Changes
-  #       uses: ad-m/github-push-action@master
-  #       with:
-  #         branch: gh-pages
-  #         directory: gh-pages
-  #         github_token: ${{ secrets.GITHUB_TOKEN }}
-  #         force: true
+  publish-docs:
+    needs: check-jobs-to-skip
+    if: ${{ github.event_name == 'push' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    defaults:
+      run:
+        shell: bash -l {0}
+    timeout-minutes: 10 # Increased timeout for docs
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Cache Conda
+        uses: actions/cache@v3
+        env:
+          CACHE_NUMBER: 1 # Match the build job cache number
+        with:
+          path: ~/conda_pkgs_dir
+          key: ${{ runner.os }}-conda-${{ env.CACHE_NUMBER }}-${{
+            hashFiles('conda/dev.yml') }}-docs
+
+      - name: Build Conda Environment
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          activate-environment: zppy_interfaces_dev
+          miniforge-variant: Miniforge3
+          miniforge-version: latest
+          environment-file: conda/dev.yml
+          channel-priority: strict
+          auto-update-conda: true
+          python-version: "3.13" # Use stable Python version for docs
+
+      - if: ${{ needs.check-jobs-to-skip.outputs.should_skip != 'true' }}
+        name: Show Conda Environment Info
+        run: |
+          conda config --set anaconda_upload no
+          conda info
+          conda list
+
+      - name: Install `zppy-interfaces` Package
+        run: python -m pip install .
+
+      # sphinx-multiversion allows for version docs.
+      - name: Build Sphinx Docs
+        run: |
+          cd docs
+          sphinx-multiversion source _build/html
+
+      - name: Copy Docs and Commit
+        run: |
+          # gh-pages branch must already exist
+          git clone https://github.com/E3SM-Project/zppy-interfaces.git --branch gh-pages --single-branch gh-pages
+
+          # Only replace main docs with latest changes. Docs for tags should be untouched.
+          cd gh-pages
+          mkdir -p _build/html
+          rm -rf _build/html/main
+          cp -r ../docs/_build/html/main _build/html/main
+          git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+
+          # The below command will fail if no changes were present, so we ignore it
+          git add .
+          git commit -m "Update documentation" -a || true
+
+      - name: Push Changes
+        uses: ad-m/github-push-action@v0.8.0
+        with:
+          branch: gh-pages
+          directory: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          force: true

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = python -msphinx
+SPHINXPROJ    = zppy-interfaces
+SOURCEDIR     = source
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/_static/style.css

@@ -0,0 +1,3 @@
+.wy-nav-content {
+    max-width: 1200px !important;
+}

docs/source/_templates/layout.html

@@ -0,0 +1,4 @@
+{% extends "!layout.html" %}
+{% block extrahead %}
+    <link href="{{ pathto("_static/style.css", True) }}" rel="stylesheet" type="text/css">
+{% endblock %}

docs/source/_templates/versions.html

@@ -0,0 +1,27 @@
+{%- if current_version %}
+<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+  <span class="rst-current-version" data-toggle="rst-current-version">
+    <span class="fa fa-book"> Other Versions</span>
+    v: {{ current_version.name }}
+    <span class="fa fa-caret-down"></span>
+  </span>
+  <div class="rst-other-versions">
+    {%- if versions.tags %}
+    <dl>
+      <dt>Tags</dt>
+      {%- for item in versions.tags %}
+      <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+      {%- endfor %}
+    </dl>
+    {%- endif %}
+    {%- if versions.branches %}
+    <dl>
+      <dt>Branches</dt>
+      {%- for item in versions.branches %}
+      <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+      {%- endfor %}
+    </dl>
+    {%- endif %}
+  </div>
+</div>
+{%- endif %}

docs/source/conf.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+import re
+
+project = "zppy-interfaces"
+author = "E3SM Project"
+copyright = f"{datetime.now():%Y}, {author}"
+
+_repo_root = Path(__file__).resolve().parents[2]
+_version_file = _repo_root / "zppy_interfaces" / "version.py"
+_version_match = re.search(
+    r'__version__\s*=\s*"([^"]+)"', _version_file.read_text(encoding="utf-8")
+)
+release = _version_match.group(1) if _version_match else "unknown"
+version = release
+
+extensions = []
+templates_path = ["_templates"]
+exclude_patterns = ["_build"]
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+html_css_files = ["style.css"]
+html_title = "zppy-interfaces documentation"
+html_sidebars = {
+    "**": [
+        "globaltoc.html",
+        "localtoc.html",
+        "relations.html",
+        "searchbox.html",
+        "versions.html",
+    ]
+}
+
+smv_tag_whitelist = r"^v.*$"
+smv_branch_whitelist = r"^(main|master)$"
+smv_remote_whitelist = r"^origin$"

docs/source/developer_global_time_series.rst

@@ -0,0 +1,51 @@
+***********************************
+Developer Guide: global_time_series
+***********************************
+
+This page describes how ``zi-global-time-series`` is implemented. For the
+runtime parameters and output-facing behavior, see :doc:`global_time_series`.
+
+Entry point and main flow
+=========================
+
+The CLI entry point is ``zppy_interfaces.global_time_series.__main__:main``.
+The implementation follows this sequence:
+
+#. ``__main__._get_args()`` parses the command-line arguments and builds a
+   ``zppy_interfaces.global_time_series.utils.Parameters`` instance.
+#. ``Parameters`` normalizes booleans, region aliases, and comma-separated plot
+   selections, then validates that the request is internally consistent.
+#. ``main()`` optionally calls ``create_ocean_ts()`` when ocean-dependent
+   classic plots are requested with ``use_ocn=True``.
+#. ``main()`` then calls ``run_coupled_global()``.
+#. ``run_coupled_global()`` builds a
+   ``zppy_interfaces.global_time_series.coupled_global.utils.RequestedVariables``
+   object, generates the plots, and optionally creates viewer HTML output.
+
+Key modules
+===========
+
+* ``zppy_interfaces/global_time_series/__main__.py`` contains the CLI parser
+  and the top-level control flow.
+* ``zppy_interfaces/global_time_series/utils.py`` defines ``Parameters`` and
+  the request normalization logic.
+* ``zppy_interfaces/global_time_series/create_ocean_ts.py`` creates ocean
+  support time series before plotting when needed.
+* ``zppy_interfaces/global_time_series/coupled_global/driver.py`` coordinates
+  original plots, component plots, and viewer generation.
+* ``zppy_interfaces/global_time_series/coupled_global/mode_pdf.py`` assembles
+  cumulative PDFs when ``make_viewer=False``.
+* ``zppy_interfaces/global_time_series/coupled_global/mode_viewer.py`` and the
+  ``mix_viewer_*`` helpers build the viewer pages when ``make_viewer=True``.
+
+Developer notes
+===============
+
+* The classic plot names in ``plots_original`` are not the same thing as raw
+  variable names, so the driver keeps them separate from the component-variable
+  lists.
+* Land plots depend on ``zppy_land_fields.csv`` for the accepted variable set,
+  grouping metadata, units, and long names.
+* The driver always writes output relative to ``results_dir``, and viewer mode
+  adds HTML pages on top of the figure generation rather than replacing the
+  underlying plot production.

docs/source/developer_guide.rst

@@ -0,0 +1,62 @@
+******************
+Developer Guide
+******************
+
+Use these pages when you want to understand how the repository is organized,
+where each CLI entry point starts, and how the internal processing flow is
+implemented.
+
+Repository layout
+=================
+
+The implementation is organized under ``zppy_interfaces``:
+
+* ``zppy_interfaces/global_time_series`` contains the global time-series CLI,
+  ocean time-series generation helpers, HTML templates, and the
+  ``zppy_land_fields.csv`` variable catalogue.
+* ``zppy_interfaces/pcmdi_diags`` contains CLI entry points for observation
+  linking, mean-climate diagnostics, variability modes, ENSO, synthetic plots,
+  and the shared setup logic used by those commands.
+* ``zppy_interfaces/multi_utils`` contains shared logging and viewer helpers
+  used by both interfaces.
+
+Interface implementation guides
+===============================
+
+.. toctree::
+   :maxdepth: 1
+
+   developer_global_time_series
+   developer_pcmdi_diags
+
+Testing
+=======
+
+.. code-block:: bash
+
+    # Set up branch
+    cd zppy-interfaces
+    git status # Check for uncommitted changes
+    git fetch upstream main
+    git checkout main
+    git reset --hard upstream/main
+    git log --oneline | head -n 1
+    # Check that we're up to date with either:
+    # 1. The latest commit on main: https://github.com/E3SM-Project/zppy-interfaces/commits/main/
+    # 2. The commits of the pull request being tested.
+
+    # Set up conda environment
+    bash # Run bash so we're in an isolated subshell
+    # Make sure conda is activated
+    rm -rf build
+    conda clean --all --y
+    conda env create -f conda/dev.yml -n env-name
+    conda activate env-name
+    pre-commit run --all-files
+    python -m pip install .
+
+    # Run unit tests
+    pytest tests/unit/global_time_series/test_*.py
+    pytest tests/unit/pcmdi_diags/test_*.py
+
+    # Note that integration testing is done as part of zppy's testing.