This is an internal documentation. There is a good chance you’re looking for something else. See Disclaimer.

About this Documentation

This documentation is based Sphinx and reStructuredText and is automatically built on Read the Docs.

Build Locally

Install Dependencies

You need tho have this dependency installed:

• python3-sphinx

• python3-sphinx-rtd-theme

• graphviz

• python3-sphinx-autobuild (optional, needed for live reload)

• jsx-lexer

On Debian-based Linux, dependencies can be installed like this:

apt install python3 python3-sphinx-rtd-theme graphviz
apt install python3-sphinx-autobuild  # optional, needed for live reload
pip install jsx-lexer

On OSX, dependencies can be installed like this (requires brew to be installed):

brew install python3
brew install graphviz

pip3 install sphinx-rtd-theme
pip3 install sphinx==4.2.0
pip3 install sphinx-autobuild
pip3 install jsx-lexer

Build the documentation

Now you can build the documentation using:

make html

The generated files can be found in _build/html/.

Live reload while you type:

make livehtml

And then visit the webpage served at http://127.0.0.1:8000. Each time a change to the documentation source is detected, the HTML is rebuilt and the page automatically reloaded.

Customizations / Extensions

This documentation offers the following extensions to Sphinx/reST:

• global.rst:

  The file /global.rst in the root directory is automatically included in all *.rst files. Use it for roles, links, etc. that need to be available globally.

• strike Role

  source:

  :strike:`some text`
  

  rendered:

  some text

• Color Roles

  source:

  :blue:`blue text`
  :green:`green text`
  :orange:`orange text`
  :red:`red text`
  

  rendered:

  blue text

  green text

  orange text

  red text

• Reference topics from this doc

  Easiest via anchor:

  .. _report-sync:

  And referenced via ref tag:

  :ref:`report-sync`

• Important extlinks roles:

  Example	Description
  :ticket:`OPS-24`	Reference ticket in Jira.
  :vshn:`TOCO-125`	Reference ticket in VSHN’s issue tracker.
  :ansible-repo:`path/to/file`	File or directory in Ansible Repository.
  :java:`path/to/object`	Reference object in Java documentation (Write java.lang.String as java/lang/String.)
  :nice:`path/to/object`	Reference object in Nice2 JavaDoc. (Write ch.tocco.AnObject as ch/tocco/AnObject.)
  :nice:`a9f...commit-id...d76`	Reference commit in Nice2 repository.

  All extlinks roles are listed in variable extlinks within /conf.py.

• Custom CSS

  CSS can be customized in /_static/css/custom.css as needed.

• Graphviz

  Graphviz can be used to draw graphs using the dot language.

  documentation and examples:

  • examples

  • more examples

  • node shapes (e.g. shape=pentagon)

  • important attributes

  • all attributes

  Example, source:

  .. graphviz::
  
     digraph {
       label="Sample Graph"
  
       # define nodes
       start [ shape=house ]
       one
       third [
           label=<neither <font color='red'>one</font><br/>nor <font color='red'>other</font>>,
           shape=diamond
       ]
       # other  # created implicitly through use
       subgraph cluster1 {
         label="Cluster"
         A
         B
       }
       lonely [ URL="https://www.tocco.ch", label="lonely\n(very)" ]
       end [ shape=circle ]
  
       # force nodes to be of same rank (=displayed at same height)
       { rank=same one other third lonely }
  
       # define connections
       start -> { one other third }
       one -> end
       third -> one
       third -> end [ penwidth=3.0 ]
       other -> end [ color=blue, label="to the end" ]
       other -> other [ label=back, fontcolor=violet ]
  
       { A B } -> lonely [ dir=both ]
     }
  

  Example, rendered: