Shinken documentation

About this documentation

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.

Contribute by...

  • 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 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
    • the original “thebasics/cgis” links spread across the documentation

Directory structure


Use only lowercase alphanumeric characters and - (minus) symbol.

Suffix filenames with the .rst extension.


Indent with 2 spaces.


Except the toctree directive, it requires a 3 spaces indentation.

Blank lines

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:

  1. = with overline
  2. =
  3. -
  4. ~

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.

Code blocks

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 {


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...


.. target-notes::

.. _`Example website`:

Documenting code

The documentation build process picks up your docstrings. See the python docstring guide.

Read the Docs v: latest
On Read the Docs
Project Home

Free document hosting provided by Read the Docs.