Editing these docs¶
This documentation is generated with Sphinx. This page describes how to contribute to the GCPy documentation.
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.
You can clean the documentation with
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.
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
H2 headers should be underlined by
H3 headers should be underlined by
H4 headers should be avoided, but if necessary, they should be underlined by
File paths occuring in the text should use the
Inline code, or references to variables in code, occuring in the text should use the
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