This document focuses on style-guide and a short reference. It is a kind of coding standards applied to documentation files. It is not about documentation content.
| Html, Online | http://docs.lonos-project.org/en/latest |
| http://readthedocs.org/projects/lonos/downloads/pdf/latest | |
| Html, as Zip | http://readthedocs.org/projects/lonos/downloads/htmlzip/latest |
This documentation uses Python-sphinx [1], which itself uses reStructuredText [2] syntax.
Use only lowercase alphanumeric characters and - (minus) symbol.
Suffix filenames with the .rst extension, so GitHub can render them.
Indent with 2 spaces.
Except:
toctreedirective requires a 3 spaces indentation.
Two blank lines before overlined sections, i.e. before H1 and H2. One blank line before other sections. See Headings for an example.
One blank line to separate directives.
Some text before.
.. note::
Some note.Exception: directives can be written without blank lines if they are only one line long.
.. note:: A short note.Technically, there's no limitation. But if possible, limit all lines to a maximum of 120 characters.
Use the following symbols to create headings:
#with overline*with overline=-^"
As an example:
##################
H1: document title
##################
Introduction text.
*********
Sample H2
*********
Sample content.
**********
Another H2
**********
Sample H3
=========
Sample H4
---------
Sample H5
^^^^^^^^^
Sample H6
"""""""""
And some text.If you need more than heading level 4 (i.e. H5 or H6), then you should consider creating a new document.
There should be only one H1 in a document.
Note
See also Sphinx's documentation about sections [3].
Use the code-block directive and specify the programming language. As
an example:
.. code-block:: python
import thisText boxes:
.. note::
Note (blue box). possible values: attention, caution, danger, error, hint, important, note, tip, warning, admonition.
Every type has its own color.will loook like:
Note
Note (blue box). possible values: attention, caution, danger, error, hint, important, note, tip, warning, admonition. Every type has its own color.
Use links and references footnotes with the target-notes directive.
As an example:
#############
Some document
#############
Link without Reference: `Example <http://www.example.com>`__
Some text which includes links to `Example website`_ and many other links.
`Example website`_ can be referenced multiple times.
(... document content...)
And at the end of the document...
**********
References
**********
.. target-notes::
.. _`Example website`: http://www.example.com/Table as CSV
.. csv-table:: Title of CSV table
:header: "Column 1", "Column 2", "Column 3"
"Sampel Row 1", Cell, Cell
"Sampel Row 2", Cell, "Cell with multiple Words"You can skip quotes, of cell content conains only a single word
Table as flat list
.. list-table:: Title of table as flat list
:header-rows: 1
* - Column 1
- Column 2
- Column 3
* - Row 1
- Cell
- Cell
* - Row 2
- Cell
- Cell:header-rows: defines the number of header rows. Skip this line, if you do not need a header.
Why is my document not linked within the table of contents?
- put the filename into index.rst. Omit the
.rstextension. - The document requires at least one section. Section names are the label that are used for the table of content.
After commiting, the documentation will not update
- The build process of the documentation takes round about 1-2 minutes.
- You can check the status here: Builds
- Check the status if the build fails
Documentation is updating, but some content is missing or malformed
- There might be some parsing errors or warnings.
Go to Builds and click on
Raw view. Check the build output for warnings and fix them.
- https://sphinx-rtd-theme.readthedocs.io/en/latest/demo/demo.html
- http://www.ericholscher.com/blog/2016/jul/1/sphinx-and-rtd-for-writers/
| [1] | http://sphinx.pocoo.org/ |
| [2] | http://docutils.sourceforge.net/rst.html |
| [3] | http://sphinx.pocoo.org/rest.html#sections |