Contributing to This Documentation
This documentation is created using Sphinx. Sphinx 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.
Sphinx uses reStructuredText as its markup language. For more information on how to write documentation using Sphinx, you can refer to
Make sure that you have conda in your path. On NERSC machines, you can load it with:
$ module load python/3.9-anaconda-2021.11
Clone the repository and checkout a branch from
$ cd <myDir> $ git clone https://github.com/<your-github-username>/zppy.git $ cd zppy $ git checkout -b <branch-name> main
Create and activate the conda development environment
$ cd <myDir>/zppy $ conda env create -f conda/dev.yml $ conda activate zppy_dev
To modify the documentation, simply edit the files under
To see the changes you made to the documentation, rebuild the web pages
$ cd <myDir>/zppy/docs $ make html
View them locally in a web browser at
Sometimes the browser caches Sphinx docs, so you might need to delete your cache to view changes.
Once you are satisfied with your modifications, commit and push them back to the repository:
$ cd <myDir>/zppy $ # `/docs/_build` is ignored by git since it does not need to be pushed $ git add . $ git commit $ git push <fork-origin> <branch-name>
OPTIONAL> If you want to generate and view versioned docs:
$ # After commiting to your branch $ cd <myDir>/zppy/docs $ sphinx-multiversion source _build/html $ # Check the `_build/html` folder for all generated versioned docs $ # Open `_build/html/<your-branch>/index.html` to view in browser
The docs version selector dropdown is in the bottom left-hand corner
Create a pull request from
Once this pull request is merged and GitHub Actions finishes building the docs, changes will be available 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 on local,
origin (the likely name for your
upstream (the likely name for your
Branches or tags that don’t contain both the sphinx
source directory and the
conf.py file will be skipped automatically.
sphinx-multiversion source _build/html --dump-metadatato see which tags/branches matched.
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.)
Create Sphinx conda environment (see above).
Create a new git branch (gh-pages):
$ git branch gh-pages $ git checkout gh-pages
Clear out anything from the main branch and start fresh
$ git symbolic-ref HEAD refs/heads/gh-pages $ rm .git/index $ git clean -fdx
accept suggested default options, except
Separate source and build directories (y/N) [n]: y
Edit Makefile and change
BUILDDIR = docs
Remove old build directory
$ rmdir build
Change the Sphinx theme to ‘ReadTheDocs’. Edit ‘source/conf.py and change
html_theme = 'alabaster'
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