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

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

Explicit item
Explicit item
1. Nested explicit item
2. Nested explicit item
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.

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
Some other entry	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.