********************************** Contributing to This Documentation ********************************** .. highlight:: none Getting Started =============== 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. 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 `_ 1. 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 2. Clone the repository and checkout a branch from ``main``: :: $ cd $ git clone https://github.com//zppy.git $ cd zppy $ git checkout -b main 3. Create and activate the conda development environment :: $ cd /zppy $ conda env create -f conda/dev.yml $ conda activate zppy_dev 4. To modify the documentation, simply edit the files under ``/docs/source``. 5. To see the changes you made to the documentation, rebuild the web pages :: $ cd /zppy/docs $ make html 6. View them locally in a web browser at ``file:////zppy/docs/_build/html/index.html``. - Sometimes the browser caches Sphinx docs, so you might need to delete your cache to view changes. 7. Once you are satisfied with your modifications, commit and push them back to the repository: :: $ cd /zppy $ # `/docs/_build` is ignored by git since it does not need to be pushed $ git add . $ git commit $ git push 8. <``OPTIONAL``> If you want to generate and view versioned docs: :: $ # After commiting to your branch $ cd /zppy/docs $ sphinx-multiversion source _build/html $ # Check the `_build/html` folder for all generated versioned docs $ # Open `_build/html//index.html` to view in browser The docs version selector dropdown is in the bottom left-hand corner 9. Create a pull request from ``/zppy/branch-name`` to ``E3SM-Project/zppy/main``. 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 ````) and ``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. - Run ``sphinx-multiversion source _build/html --dump-metadata`` to 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 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: :: Commit and push back to Github: :: $ git add . $ git commit $ git push origin gh-pages