Editing this User Guide

This user guide is generated with Sphinx. Sphinx is an open-source Python project designed to make writing software documentation easier. The documentation is written in reStructuredText (reST), a plaintext markup language that Sphinx extends for software documentation. The source for the documentation is the docs/source directory in top-level of the source code (and its subdirectories).

Quick start

First-time setup: Install Sphinx

To build this user guide on your local machine, you need to install Sphinx and its dependencies, which are listed in the table below.

Package	Description	Version
sphinx	Creates online user manual documentation from markup text files	7.2.6
sphinx-autobuild	Dynamically builds Sphinx documentation and displays it in a browser	2021.3.14
sphinx_rtd_theme	Sphinx theme for ReadTheDocs	2.0.0
sphinxcontrib-bibtex	Inserts LaTeX-style bibliography citations into ReadTheDocs documentation	2.6.2
docutils	Processes plaintext documentation into HTML and other formats	0.20.1
recommonmark	Parses text for docutils	0.7.1
jinja2	Replaces tokenized strings with text	3.1.6

We recommend that you create a standalone Conda environment to install Sphinx and its dependencies. The YAML file docs/read_the_docs_environment.yaml contains the proper package specifications. Use these commands:

$ cd docs
$ conda env create -n rtd_env --file=read_the_docs_environment.yml

This step only needs to be done once.

Build the documentation

Activate the Conda environment containing Sphinx and its dependencies:
```
$ conda activate rtd_env
```

Navigate to the docs/ folder:

(rtd_env) $ cd docs     # Skip if you are already in the docs folder

Check out the docs/dev branch of this repository, as this is the branch from which the latest ReadTheDocs version will be built:
```
(rtd_env) $ git checkout docs/dev   # Skip if you are already on the docs/dev branch
```
Start the sphinx-autobuild server:
```
(rtd_env) $ sphinx-autobuild source build/html
```
This will parse the reST-format files in the docs/source/ directory tree and generate new HTML files in docs/build/html.
Remove any HTML files (in docs/build/html) that might be left behind from a previous build:
```
(rtd_env) $ make clean
```
Open a web browser and navigate to localhost:8000.
Open your favorite text editor and start making changes to the reST-format documentation files in the docs/source directory tree. While sphinx-autobuild is running, you will see your updates rendered in the web browser as soon as you soon as you save your changes to disk.
Once you are satisfied with your edits, commit your changes to Git and push the documentation to the docs/dev remote branch of this repository,
Remove the generated HTML documentation files:
```
(rtd_env) $ make clean
```
Halt the sphinx-autobuild server by typing CTRL-C.
Deactivate the Conda environment:
```
(rtd_env) $ conda deactivate
```

Learning reStructured Text

ReadTheDocs documentation is generated from text files in reStructured Text (reST), which is an easy-to-read, what-you-see-is-what-you-get plaintext markup language. It is the default markup language used by Sphinx.

Writing reST can be tricky at first. Whitespace matters, and some directives can be easily miswritten. Two important things you should know right away are:

Indents are 3-spaces
“Things” are separated by 1 blank line. For example, a list or code-block following a paragraph should be separated from the paragraph by 1 blank line.

You should keep these in mind when you’re first getting started. Dedicating an hour to learning reST will save you time in the long-run. Below are some good resources for learning reST.

reStructuredText primer: (single best resource; however, it’s better read than skimmed)
Official reStructuredText reference (there is a lot of information here)
Presentation by Eric Holscher (co-founder of Read The Docs) at DjangoCon US 2015 (the entire presentation is good, but reST is described from 9:03 to 21:04)
YouTube tutorial by Audrey Tavares

A good starting point would be Eric Holscher’s presentations followed by the reStructuredText primer.

Style guidelines

This user guide is written in semantic markup. This is important so that the user guide remains maintainable. Before contributing to this documentation, please review our style guidelines (below). When editing the source, please refrain from using elements with the wrong semantic meaning for aesthetic reasons. Aesthetic issues can be addressed by changes to the theme.

Titles and headers

Element	reST Markup
Section header (aka “Heading 1)	Overline by `#` and underline by `#`
Sub-section header (aka “Heading 2”)	Overline by `=` and underline by `=`
Sub-sub-section header (aka “Heading 3”)	Underline by `-`
Sub-sub-sub-section header (aka “Heading 4”)	Underline by `~`
Sub-sub-sub-sub-section header (aka “Heading 5”)	Underline by `^`

References and links

Element	reST Markup Example	Rendered text
Reference to a named anchor	:ref:`editing_this_user_guide_quickstart`	Quick start
Renamed reference to a named anchor	:ref:`Getting Started <editing_this_user_guide_quickstart>	Getting Started
HTML link	`ReadTheDocs <https://geos-chem.readthedocs.io>`_	GEOS-Chem Manual

Other common style elements

Element	reST Markup Example	Rendered text
File paths	:file:`myfile.nc`	`myfile.nc`
Directories	:file:`/usr/bin`	`/usr/bin`
Program names	:program:`cmake`	cmake
OS-level commands	:program:`rm -rf`	rm -rf
Environment variables	:envvar:`$HOME`	`$HOME`
Inline code or code variables	:code:`PRINT*, "HELLO!"`	`PRINT*, "HELLO!"`
Inline literal text	:literal:`$`	`$`

Indented code and text blocks

Code snippets should use .. code-block:: <language> directives:

Python

.. code-block:: python

   import gcpy
   print("hello world")

Renders as:

import gcpy
print("hello world")

Fortran

.. code-block:: Fortran

   DO I = 1, 10
      PRINT*, I
   ENDDO

Renders as:

DO I = 1, 10
   PRINT*, I
ENDDO

Bash

.. code-block:: bash

   #!/bin/bash

   for f in *.nc; do
       echo $f
   done

Renders as:

#!/bin/bash

for f in *.nc; do
    echo $f
done

Command line (aka “console”)

.. code-block:: console

   $ ls -l $HOME

Renders as:

$ ls -l $HOME

No formatting

.. code-block:: none

   This text renders without any special formatting.

Renders as:

This text renders without any special formatting.