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 a reStructuredText (it’s similar to markdown), which Sphinx extends for software documentation.
The source for the documentation is the docs/source
directory in top-level of the source code.
Quick start¶
To build this user guide on your local machine, you need to install Sphinx. Sphinx is a Python 3 package and
it is available via pip. This user guide uses the Read The Docs theme, so you will also need to
install sphinx-rtd-theme
. It also uses the sphinxcontrib-bibtex
and recommonmark extensions, which you’ll need to install.
$ cd $KPP_HOME/docs
$ pip install -r requirements.txt
Installing with requirements.txt
will make sure that the
proper versions of Sphinx and its dependencies will be installed.
To build this user guide locally, navigate to the docs/
directory and make the html
target.
$ cd $KPP_HOME/docs
$ make html
This will build the user guide in docs/build/html
, and you can
open index.html
in your web-browser. The source files for the
user guide are found in docs/source
.
Note
You can clean the documentation with make clean
.
Learning reST¶
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)
A good starting point would be Eric Holscher’s presentations followed by the reStructuredText primer.
Style guidelines¶
Important
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.
For titles and headers:
Section headers should be underlined by
#
charactersSubsection headers should be underlined by
-
charactersSubsubsection headers should be underlined by
^
charactersSubsubsubsection headers should be avoided, but if necessary, they should be underlined by
"
characters
File paths (including directories) occuring in the text should use
the :file:
role.
Program names (e.g. cmake) occuring in the text should
use the :program:
role.
OS-level commands (e.g. rm) occuring in the text should
use the :command:
role.
Environment variables occuring in the text should use the
:envvar:
role.
Inline code or code variables 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 (e.g. the $
above) should use the
:literal:
role.