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

Directory structure

Filenames

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

Suffix filenames with the .rst extension.

Indentation

Indent with 2 spaces.

Attention

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.

Headings

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 {
      parameter
  }

References

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/

Documenting code

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

Read the Docs v: latest
Versions
latest
stable
branch-1.4
2.4.1
2.2
2.0.3
1.4.2
Downloads
pdf
htmlzip
epub
On Read the Docs
Project Home
Builds

Free document hosting provided by Read the Docs.