Contributing to this documentation¶
Create a conda environment¶
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.
First, make sure that you have conda in your path. On NERSC machines, you can load it with:
$ module load python3/3.7-anaconda-2019.07
Create a new conda environment, install Sphinx as well as the Sphinx readthedocs theme
$ conda create -n sphinx
$ conda activate sphinx
$ conda install -c anaconda sphinx
$ pip install sphinx_rtd_theme
Checkout and edit documentation¶
The documentation is maintained in the Github repository under a separate branch named ‘gh-pages’. This special branch is used by Github.com to directly serve static web pages (see GitHub Pages).
Clone the repository and checkout the ‘gh-pages’ branch:
$ cd <myDir>
$ git clone git@github.com:E3SM-Project/zstash.git zstash
$ cd zstash
$ git checkout gh-pages
You should now see two sub-directories: source contains the documentation source files, and docs the html web pages created by Sphinx.
To modify the documentation, simply edit the files under source. Sphinx uses reStructuredText as its markup language. For more information on how to write documentation using Sphinx, you can refer to
To see the changes you made to the documentation, rebuild the web pages
$ cd <myDir>/zstash
$ make html
and view them locally in a web browser at file:///<myDir>/zstash/index.html.
Sphinx may occasionally not build the new files properly. If that is the case, try removing the docs sub-directory (be careful not to remove source) and rebuild entirely:
$ cd <myDir>/zstash
$ rm -r docs
$ make html
Once you are satisfied with your modifications, commit and push them back to the repository:
$ cd <myDir>/zstash
$ git add .
$ git commit
$ git push origin gh-pages
Your changes will then be available on the zstash documentation page.
Initial setup (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 master 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