Add documentation for zppy-interfaces

[Copilot]

Summary

Objectives:

• Add documentation for zppy-interfaces -- covering user guide and developer guide for both major components: global_time_series & pcmdi_diags

Issue resolution:

• Resolves Add documentation #2

Select one: This pull request is...

• a bug fix: increment the patch version
• a small improvement: increment the minor version
• a new feature: increment the minor version
• an incompatible (non-backwards compatible) API change: increment the major version

Small Change

• To merge, I will use "Squash and merge". That is, this change should be a single commit.
• Logic: I have visually inspected the entire pull request myself.
• Pre-commit checks: All the pre-commits checks have passed.

[forsyth2]

To generate docs:

git fetch upstream
git checkout -b copilot/documentation-for-zppy-interfaces upstream/copilot/documentation-for-zppy-interfaces
lcrc_conda # Activate conda
conda clean --all --y
conda env create -f conda/dev.yml -n zi-pr51
python -m pip install .  

cd docs
make html
cp -r _build/ /lcrc/group/e3sm/public_html/diagnostic_output/ac.forsyth2/zi_docs

Docs are then available at https://web.lcrc.anl.gov/public/e3sm/diagnostic_output/ac.forsyth2/zi_docs/html/

[forsyth2]

@copilot I added a developer guide. Can you make global_time_series and pcmdi_diags subpages for it? Similarly, there should be a user guide with global_time_series and pcmdi_diags subpages. That is, documentation should be categorized by whether it's relevant to users or to developers. For example, a user would want a step-by-step guide to running, a developer would want a step-by-step guide to how the code works.

[Copilot]

@copilot I added a developer guide. Can you make global_time_series and pcmdi_diags subpages for it? Similarly, there should be a user guide with global_time_series and pcmdi_diags subpages. T...

Addressed in eb6b62f. Added a new user_guide with global_time_series and pcmdi_diags subpages, and added matching developer-focused subpages under developer_guide.

[Copilot]

Pull request overview

This PR introduces an initial Sphinx documentation scaffold for zppy-interfaces,
splitting guidance by audience (user vs. developer) and documenting the CLI entry
points for global_time_series and pcmdi_diags.

Changes:

• Add Sphinx docs scaffold (config, Makefile, templates, and shared styling).
• Add audience-based docs structure (home page + user/developer guide indices).
• Add detailed user/developer pages for zi-global-time-series and PCMDI-related
  CLIs, and re-enable docs publishing in CI.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
docs/source/index.rst	Adds docs home page with audience-based navigation.
docs/source/user_guide.rst	Adds user guide landing page and toctree.
docs/source/developer_guide.rst	Adds developer guide landing page plus testing instructions (needs directive indentation fix).
docs/source/global_time_series.rst	Adds user-facing runtime guide and parameter reference for zi-global-time-series.
docs/source/developer_global_time_series.rst	Adds developer-facing module/flow map for global_time_series.
docs/source/pcmdi_diags.rst	Adds user-facing runtime guide and parameter references for PCMDI-related CLIs.
docs/source/developer_pcmdi_diags.rst	Adds developer-facing module/flow map for pcmdi_diags.
docs/source/conf.py	Adds Sphinx configuration (theme, sidebar, version extraction).
docs/source/_templates/layout.html	Adds template override to include custom CSS.
docs/source/_templates/versions.html	Adds version switcher sidebar template for multiversion builds.
docs/source/_static/style.css	Adds shared CSS tweaks (content width).
docs/Makefile	Adds Sphinx Makefile wrapper.
.github/workflows/build_workflow.yml	Re-enables docs publishing job (currently has a YAML syntax error and workflow logic/pinning issues).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[forsyth2]

@copilot Please implement the suggestions from the code review

[Copilot]

@copilot Please implement the suggestions from the code review

Implemented the review suggestions in commit 736a4fb.

[Copilot]

@copilot Some cells in the parameter table are showing up with an empty bullet point. I looks to be caused by lines like:

   * - ``--debug``

...

Fixed everywhere those lone - table cells occurred by replacing them with N/A so they no longer render as empty bullets. Addressed in daab45c.

[forsyth2]

I read through the rendered docs (latest: https://web.lcrc.anl.gov/public/e3sm/diagnostic_output/ac.forsyth2/zi_docs_review/html/index.html). They look good to me. For perfect accuracy, I'd need to go through the code line-by-line and compare but I think the read-through should be sufficient.

I reviewed the code files in the diff for the non-rst files as well.

[forsyth2]

@chengzhuzhang @zhangshixuan1987 Do either of you have any objections if I merge these documentation updates? Let me know if you'd like to review them first.

For reference, zppy-interfaces still doesn't have documentation, so this PR finally adds it (user and developer guides for both global_time_series and pcmdi_diags). Latest rendering: https://web.lcrc.anl.gov/public/e3sm/diagnostic_output/ac.forsyth2/zi_docs_review/html/index.html.

My hope is that going forward, relevant doc changes will be included in zppy-interfaces PRs along with their associated code & test changes.

[forsyth2]

@copilot Can you please give directions for ensuring the docs are actually built after we merge this PR?

zppy's documentation has these directions:

Initial setup (obsolete/for reference only)
===========================================

The instructions below only apply for the initial configuration of the
Sphinx documentation on the Github repository. They are documented here
for reference only. Do not follow them unless you are setting up documentation
for a new repository. (Adapted from `Sphinx documentation on GitHub
<http://datadesk.latimes.com/posts/2012/01/sphinx-on-github>`_.)

Create Sphinx conda environment (see above).

Create a new git branch (gh-pages): ::

  $ git branch gh-pages
  $ git checkout gh-pages

Clear out any­thing from the main branch and start fresh ::

  $ git symbolic-ref HEAD refs/heads/gh-pages
  $ rm .git/index
  $ git clean -fdx

Create documentation ::

  $ sphinx-quickstart

accept suggested default options, except ::

  Separate source and build directories (y/N) [n]: y

Edit Makefile and change ``BUILDIR`` ::

  BUILDDIR = docs

Remove old build directory ::

  $ rmdir build

Change the Sphinx theme to 'ReadTheDocs'. Edit 'source/conf.py and change ::

  html_theme = 'alabaster'

to ::

  import sphinx_rtd_theme
  html_theme = "sphinx_rtd_theme"
  html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

Try building documentation ::

  $ make html

Create an empty .nojekyll file to indicate to Github.com that this
is not a Jekyll static website: ::

  $ touch .nojekyll

Create a top-level re-direction file: ::

  $ vi index.html

with the following: ::

  <meta http-equiv="refresh" content="0; url=./docs/html/index.html" />

Commit and push back to Github: ::

  $ git add .
  $ git commit
  $ git push origin gh-pages

[Copilot]

@copilot Can you please give directions for ensuring the docs are actually built after we merge this PR?

zppy's documentation has these directions:
...

Acknowledged: I will only provide a comment (no commit, no PR summary changes).

After merge, docs are built and published automatically by GitHub Actions:

1. Merge this PR into main.
2. In GitHub Actions, open the latest CI/CD Build Workflow run triggered by that push.
3. Confirm the publish-docs job ran and passed, especially:
   • Build Sphinx Docs
   • Copy Docs and Commit
   • Push Changes
4. Confirm gh-pages was updated at _build/html/main.
5. Verify the rendered site at:
   • https://docs.e3sm.org/zppy-interfaces/
   • (or direct) https://e3sm-project.github.io/zppy-interfaces/_build/html/main/

For release tags, docs are also published by the CI/CD Release Workflow on GitHub release publish.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

[forsyth2]

https://web.lcrc.anl.gov/public/e3sm/diagnostic_output/ac.forsyth2/zi_docs_review/html/index.html is still the latest rendering since the only code change since then has been 6b35ba4, which only touched the GitHub workflow.

[forsyth2]

I've done a read-through of the latest rendered docs.

I've also confirmed there have been no merges to https://github.com/E3SM-Project/zppy-interfaces/commits/main/ since I started this PR, so there's no need to document later code changes, as we had to do in E3SM-Project/zppy#839.

I think this is ready to merge. Since this is zppy-interfaces's first documentation, we'll have to confirm the docs workflow works properly and actually renders the docs. To include them on docs.e3sm.org we'll have to make a PR to E3SM-Project.github.io, specifically, docs/index.md and mkdocs.yaml. Alternatively, we could just make a PR to update the zppy docs to point to them, which is likely sufficient considering virtually all users will be interacting with zppy-interfaces via zppy.

[forsyth2]

The docs building action failed with:

# gh-pages branch must already exist
Cloning into 'gh-pages'...
fatal: Remote branch gh-pages not found in upstream origin

Based on Claude's suggestions, I ran:

git checkout --orphan gh-pages
git rm -rf .
git commit --allow-empty -m "Initialize gh-pages branch"
git push upstream gh-pages

That then launched a new action. That page says the link is https://docs.e3sm.org/zppy-interfaces/, but that gives a 404 error. It looks like the base link https://e3sm-project.github.io/zppy-interfaces does already auto-redirect to https://docs.e3sm.org/zppy-interfaces/, again giving the 404 error.

[forsyth2]

Iterating with Claude more, I merged #52, which launched this action, which completed successfully. https://docs.e3sm.org/zppy-interfaces/, however, still gives a 404.

https://docs.e3sm.org/zppy-interfaces/_build/html/main/index.html also gives a 404.

[forsyth2]

git checkout gh-pages
touch .nojekyll
git add .nojekyll
git commit -m "Add empty .nojekyll file"
git push upstream gh-pages # Fails

git fetch upstream gh-pages
git rebase upstream/gh-pages
git log --oneline | cat
# a92816a Add empty .nojekyll file
# 07bdba5 Update documentation # (Automated GitHub commit)
# ce7fb05 Initialize gh-pages branch
git push upstream gh-pages

That launches this action. That completes successfully, but both https://docs.e3sm.org/zppy-interfaces/ and https://docs.e3sm.org/zppy-interfaces/_build/html/main/index.html still give a 404.

[forsyth2]

I switched to Copilot Chat, which added this commit, which simply adds a file CNAME containing docs.e3sm.org to the top-level of the gh-pages branch. And now the docs do render: https://docs.e3sm.org/zppy-interfaces/_build/html/main/index.html