Contributing to This Documentation

Getting Started

This documentation is created using Sphinx, which is an open-source tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.

The documentation is maintained in the main branch of the GitHub repository. You can include code and its corresponding documentation updates in a single pull request (PR).

After merging a PR, GitHub Actions automates the documentation building process. It pushes the HTML build to the gh-pages branch, which is hosted on GitHub Pages.

Edit Documentation

Sphinx uses reStructuredText as its markup language. For more information on how to write documentation using Sphinx, you can refer to

• First Steps with Sphinx

• reStructuredText Primer

# Sphinx is included in the dev environment,
# so we just need to set one up:
cd zppy
conda clean --all --y
conda env create -f conda/dev.yml -n env-name
python -m pip install .

# Now, we can produce the documentation locally:
cd docs
make html

# And transfer it to a web server path so we can see it online.

# Example web server paths:
# Chrysalis: /lcrc/group/e3sm/public_html/diagnostic_output -> https://web.lcrc.anl.gov/public/e3sm/diagnostic_output
# Compy: /compyfs/www -> https://compy-dtn.pnl.gov
# Perlmutter: /global/cfs/cdirs/e3sm/www -> https://portal.nersc.gov/cfs/e3sm

# For more machines, go to:
# https://github.com/E3SM-Project/mache/tree/main/mache/machines
# Select the cfg for the machine, and find the `[web_portal]`` section.
# That will show the `base_path` and `base_url`.

cp -r _build/ base_url/$USER/zppy_docs
# Needs to be 755 to show up on https://portal.nersc.gov/cfs/e3sm
chmod -R 755 base_url/$USER/zppy_docs

# Optional -- if you want to generate and view versioned docs:
sphinx-multiversion source _build/html

Pull requests should bundle together associated code changes, test changes, and documentation changes. Once you’ve merged your pull request and GitHub Actions finishes building the docs, changes will be visible on the zppy documentation page.

How Documentation is Versioned

The sphinx-multiversion package manages documentation versioning.

sphinx-multiversion is configured to generate versioned docs for available tags and branches. Ones that don’t contain both the sphinx source directory and the conf.py file will be skipped automatically.

• Run sphinx-multiversion source _build/html --dump-metadata to see which tags/branches matched.