This documentation uses Python-sphinx [2], which itself uses reStructuredText [3] syntax.
The guidelines below are loosely based on the documentation-style-guide-sphinx [1] project and improve upon the converted content of the numerous of contributors to the shinken wiki.
- Removing all duplicate files / content from the source tree
- Split the configuration parameters that are unused from the unimplemented ones
- Remove the nagios and nagios-specific references (such as unused parameters) from the various pages
- Clean up the gettingstarted / installations section
- Fix the internal links on the “troubleshooting/troubleshooting-shinken” page
- Dedicate a basic page on how to use the shinken.io packs
- Shorten the directory names in the source directory for shorter links
- Find or create the correct targets for:
- the “configuringshinken/objectdefinitions#retention_notes” links, referenced multiple times by
- “configobjects/service”
- “configobjects/host”
- the “internal_metrics” links, or create the page based on http://www.shinken-monitoring.org/wiki/internal_metrics
- the original “thebasics/cgis” links spread across the documentation
Use only lowercase alphanumeric characters and -
(minus) symbol.
Suffix filenames with the .rst
extension.
Indent with 2 spaces.
Attention
Except the toctree
directive, it requires a 3 spaces indentation.
Two blank lines before overlined sections, i.e. before H1 and H2. See Headings for an example.
One blank line to separate directives.
Some text before.
.. note::
Some note.
On multiple lines.
Exception: directives can be written without blank lines if they are only one line long.
.. note:: A short note.
Use the following symbols to create headings:
=
with overline=
-
~
If you use more then 4 levels, it’s usually a sign that you should split the file into a subdirectory with multiple chapters.
As an example:
==================
H1: document title
==================
Introduction text.
Sample H2
=========
Sample content.
Another H2
==========
Sample H3
---------
Sample H4
~~~~~~~~~
And some text.
There should be only one H1 in a document.
Note
See also Sphinx’s documentation about sections [4].
Use the code-block
directive and specify the programming language if appropriate. As
an example:
.. code-block:: python
import this
The :: directive works for generic monospaced text as used in configuration files and shell commands
::
define {
parameter
}
The definition of a target for a link is done by placing an anchor.
.. _path-to-file/rst-filename: // placed on top of every file
.. _path-to-file/index: // placed in every index file, in every subdirectory of the source directory
.. _path-to-file/subdirectory/rst-filename: // placed on top of a file in a subdirectory
.. _path-to-file/rst-filename#anchor_on_the_page: // placed as an in-page anchor to a title
Anchor on the page
------------------
Links to the above anchors are made with the :ref:
directive
:ref:`this is a reference of the first anchor <path-to-file/rst-filename>`.
:ref:`this is a reference of the last anchor <path-to-file/rst-filename#anchor_on_the_page>`
Note that we use underscores in the in-page anchors on titles, but use the -
(minus) symbol in the rest of the links.
This has the advantage that a part of the file path can be copy-pasted when building links and only in-page anchors on titles need some extra care when making links.
Optional when using a lot of references: use reference footnotes with the target-notes
directive.
As an example:
=============
Some document
=============
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/
The documentation build process picks up your docstrings. See the python docstring guide.