Editing these docs
This documentation is generated with Sphinx. This page describes how to contribute to the GCPy documentation.
Quick start
You need the Sphinx Python to build (and therefore edit) this documentation. Assuming you already have Python installed, install Sphinx:
$ pip install sphinx
To build the documentation, navigate to gcpy/docs
and make the html target:
gcuser:~$ cd gcpy/docs
gcuser:~/gcpy/docs$ make html
This will generate the HTML documentation in gcpy/docs/build/html
from the reST files in
gcpy/docs/source
. You can view this local HTML documentation by opening
index.html
in your web-browser.
Note
You can clean the documentation with make clean
.
Learning reST
Writing reST can be a bit tricky at first. Whitespace matters (just like in Python), 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 (e.g., 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)
A good starting point would be Eric Holscher’s presentations followed by reading the reStructuredText primer.
Style guidelines
Important
This documentation is written in semantic markup. This is important so that the documentation remains maintainable by the GEOS-Chem Support Team. Before contributing to this documentation, please review our style guidelines. When editing the documentation, please refrain from using elements with the wrong semantic meaning for aesthetic reasons. Aesthetic issues should be addressed by changes to the theme (not changes to reST files).
For titles and headers:
H1 titles should be underlined by
#
charactersH2 headers should be underlined by
-
charactersH3 headers should be underlined by
^
charactersH4 headers should be avoided, but if necessary, they should be underlined by
"
characters
File paths occuring in the text should use the :literal:
role.
Inline code, or references to variables in code, occuring in the text should use the :code:
role.
Code snippets should use .. code-block:: <language>
directive like so
.. code-block:: python
import gcpy
print("hello world")
The language can be “none” to omit syntax highlighting.
For command line instructions, the “console” language should be used. The $
should be used
to denote the console’s prompt. If the current working directory is relevant to the instructions,
a prompt like gcuser:~/path1/path2$
should be used.
Inline literals (such as the $
above) should use the :literal:
role.