How to contibute to this documentation

Note

Always start a file with reference to itself. E.g the first lines of this file look like this:

.. _projects/howto_document:

**************************************
How to contibute to this documentation
**************************************

In order to allow proper cross-referencing later, use one of the following pre-fixes:

• framework/ - For all framework related documentation
• devices/ - For all device related documentation
• projects/ - For documentation about karabo projects or setups

Headers

Only use one top header (section header) per file.

Top headers use stars (“*”) as surrounding. Sub-headers are underlined by “=”, “+”, “_” and “^” in this order.

Sub-Header

Sub-Sub Header

Sub-Sub-Sub Header

Headers
=======

Sub-Header
----------

Sub-Sub Header
++++++++++++++

Sub-Sub-Sub Header

Paragraphs

This text reflects a regular paragraph. Use the same indentation and separate text by adding one or more blank lines.

Do not use more than 80 characters per line.

Inline Markup

Inline markup should go like this: emphasis, strong emaphasis, code related. Escaping is sometimes needed, use a backslash if you want to show e.g. *, \, `.

Always use double backticks if you want to refer to a class or function, like: void foo()

Inline markup should go like this: *emphasis*, **strong emaphasis**,
``code related``. Escaping is sometimes needed, use a backslash if you want
to show e.g. \*, \\, \`.

Always use double backticks if you want to refer to a class or function, like:
``void foo()``

Lists

• Bulleted item
• Bulleted item
  • Nested bulleted item (watch the blank line)
  • Nested bulleted item
• Bulleted item

1. Numbered item
2. Numbered item
   1. Nested numbered item (watch the blank line)
   2. Nested numbered item
3. Numbered item 3

1. Explicit item
2. Explicit item
   1. Nested explicit item
   2. Nested explicit item
3. Explicit item

* Bulleted item
* Bulleted item

  * Nested bulleted item (watch the blank line)
  * Nested bulleted item

* Bulleted item


#. Numbered item
#. Numbered item

   #. Nested numbered item (watch the blank line)
   #. Nested numbered item

#. Numbered item 3


1. Explicit item
2. Explicit item

   a. Nested explicit item
   b. Nested explicit item

3. Explicit item

Links

Use Link text for inline web links.

Internal links should look like this :ref:`framework/howto_document`, which refers to the own section.

Use `Link text <http://xfel.eu>`_ for inline web links.

Internal links should look like this :ref:`framework/howto_document`,
which refers to the own section.

Special Directives

Topic title

This is a topic. Something that highlights in a box.

See also

This is a seealso.

Note

This is a note.

Warning

This is a warning.

.. topic:: Topic title

   This is a topic. Something that highlights in a box.

.. seealso::

   This is a seealso.

.. note::

   This is a note.

.. warning::

   This is a warning.

.. todo::

   This is a todo note.

.. ifconfig:: includeDevInfo is True

   This is information that is very detailed and can be switched off during
   rendering.

Tables

Simple tables are formatted like so:

A	B	A and B
False	False	False
True	False	False
False	True	False
True	True	True

=====  =====  =======
  A      B    A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

Complex tables are formatted like so:

Title 1	Title 2
Some entry	Single row
Some other entry	Split row
	Split row

+------------------+-------------------------------------------------------+
|**Title 1**       |**Title 2**                                            |
+------------------+-------------------------------------------------------+
|Some entry        |Single row                                             |
+------------------+-------------------------------------------------------+
|Some other entry  |Split row                                              |
|                  +-------------------------------------------------------+
|                  |Split row                                              |
+------------------+-------------------------------------------------------+

Code

Code blocks are initiated by

@Slot
def foo(self):
    """Does nothing"""
    pass

KARABO_REGISTER_SLOT(foo);
void foo() {
    // Does nothing
}

 .. code-block:: Python

@Slot
def foo(self):
    """Does nothing"""
    pass

KARABO_REGISTER_SLOT(foo);
void foo() {
    // Does nothing
}

Images and Figures

To add an image use:

.. image:: _images/darthvader.jpg

.. figure:: _images/xfel.jpg
    :align: center
    :height: 100px
    :alt: alternate text
    :figclass: align-center

Figures are like images but with a caption

.. image:: _images/darthvader.jpg

.. figure:: _images/xfel.jpg
    :align: center
    :height: 100px
    :alt: alternate text
    :figclass: align-center

    Figures are like images but with a caption

Graphs

Drawing of graphs is also supported:

Examples

.. graphviz::

   digraph {
      "From" -> "To";
   }

.. digraph:: example

   "device1" [shape=circle, style=filled, fillcolor=green]
   "device2" [shape=circle, style=filled, fillcolor=orange]
   "broker"  [shape=box, height=2, style=filled, fillcolor=gray]

   "device1" -> "broker"
   "device2" -> "broker"

Math

\[n_{\mathrm{offset}} = \sum_{k=0}^{N-1} s_k n_k\]

.. math::

    n_{\mathrm{offset}} = \sum_{k=0}^{N-1} s_k n_k

Footnotes

Some text that requires a footnote [1] .

Footnotes

[1]	Text of the first footnote.

Some text that requires a footnote [#f1]_ .

.. rubric:: Footnotes

.. [#f1] Text of the first footnote.