Style guide and RST examples

Documentation and useful Links

Our TUM-Chat Channel
Anleitung DOCX -> RST mit pandoc und unzip https://peintinger.com/?p=365
Sphinx documentation https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
ReadTheDocs Sphinx Theme Documentation https://sphinx-rtd-theme.readthedocs.io/en/stable/
reStructuredText Official Docs

RST style guidelines

No line longer than 80 characters
Place folder number at teh begining of all labels (see below).

Sections

Note

All section markers are always 80 characters log.

# with overline, for parts
* with overline, for chapters
=, for sections
-, for subsections
^, for subsubsections
", for paragraphs

###############################################################################
Headline 1
###############################################################################
Some text...

*******************************************************************************
Headline 2
*******************************************************************************
Some text...

Headline 3
===============================================================================
Some text...

Headline 4
-------------------------------------------------------------------------------
Some text...

Highlighting

Some examples for in-text highlighting:

*italic* –> italic
**bold** –> bold
``mono-space`` –> mono-space

For very important stuff several special roles are available:

.. rubric:: This is a rubric. It is a paragraph heading that does not appear in TOCs.

.. note:: This is a note.

.. tip:: This is a tip.

.. warning:: This is a warning.

.. todo:: This is a todo.

.. seealso:: This is a see also.

.. versionadded:: v1.2.1

.. versionchanged:: v1.2.1

.. centered:: This directive creates a centered boldfaced line of text.

This is a rubric. It is a paragraph heading that does not appear in TOCs.

Note

This is a note.

Tip

This is a tip.

Warning

This is a warning.

Todo

This is a todo.

References & labels

External Links

Official docs - Hyperlinks

External URL with label: `URL Label <https://url.de>`_
External URL without label: `<https://url.de>`_
Or split link and target definition:
- `a link`_.
- .. _a link: https://the-url.de/

Cross-referencing

Official docs - Roles - Cross referencing

Referencing documents

Reference another document (or file) like this:

:doc:`../01-einfuehrung-arc-gis/index` –> Einführung in ArcGIS

:doc:`Kapitel 1 <../../data-science/visualization/grafana>` –> Kapitel 1

Use syntax above with relative path to the document to be referenced!

Reference a label

Create label: .. _labelName:
Reference label: :ref:`labelName` or :ref:`Label text <labelName>`

Note

Labels names should be unique accross the entire documentation, not just this file.

Note

Labels need to be followed by a blank line.

Referencing sections

This works for referencing sections in the same and other documents.

Create a unique reference label before section heading: .. _the_ref_label_name:
One blank line between label and headline.
Reference this in another or same document:

:ref:`postgrest-prepare-database`. –> Shows the referenced headline.

:ref:`THIS TEXT IS SHOWN <postgrest-prepare-database>` –> shows THIS TEXT IS SHOWN.

.. _00-the-headline-text:

The headline text
-------------------------------------------------------------------------------

We reference the section header above like this: :ref:`00-the-headline-text`.
Or like this :ref:`THIS text is shows <00-the-headline-text>`.

Auto section labels

The sphinx.ext.autosectionlabel extension creates labels for each section automatically, as described here

This is a reference to a section in the same document:
:ref:`00-template/index:Auto section labels`

This references a section in another document:
:ref:`04-routing/index:Service Area und Routing`.

This is the same reference with custom text:
This references a section in another document
:ref:`Section abc. <04-routing/index:Service Area und Routing>`.

Or the same using ``numref:``: :numref:`04-routing/index:Service Area und Routing`.

This is a reference to a section in the same document: Auto section labels

This references a section in another document: 04-routing/index:Service Area und Routing.

This is the same reference with custom text: This references a section in another document Section abc..

Or the same using numref:: 04-routing/index:Service Area und Routing.

Emojies 🆒

Usage: |:smiley-code:|. The bars and colons are required! 😄

Images and Figures

Official docs - images

Inline images

Official docs - inline images

Inline images are images within a line of text. Make sure to scale inline images so the don’t increase line spacing.

This text containers an inline image now and the text continues. More text, more text, more text, more text, more text, more text, more text, , more text, more text, more text, image again , more text, more text , more text, more text, more text.

This text containers an inline image now |inline-img| and the text continues.
More text, more text, more text, more text, more text, more text, more text,
, more text, more text, more text, image again |inline-img|, more text, more text
, more text, more text, more text.

.. |inline-img| image:: ../favicon_tum_neg.svg
  :width: 25 px

Figures

Official docs - figures

Figures are images with caption and legend.

TUM — This is an image caption giving useful information.

This is an image legend for even more information (we won’t need this, I assume).

In this text I reference the image above: This is an image caption giving useful information. Or like this: TheImageAbove

The code below produces the image, image caption and text with reference to the image above.

.. figure:: ../favicon_tum_neg.svg
  :width: 200 px
  :alt: TUM
  :align: center
  :scale: 100 %
  :target: https://www.gis.lrg.tum.de/
  :name:  00_image_label

  This is an image caption giving useful information.

  This is an image legend for even more information
  (we won't need this, I assume).

In this text I reference the image above: :ref:`00_image_label`
Or like this: :ref:`TheImageAbove <00_image_label>`

Numeric references to figures

To put numeric references to figures the :numref: role can be used.

.. figure:: ../favicon_tum_neg.svg
  :width: 200 px
  :alt: TUM
  :align: center
  :scale: 100 %
  :target: https://www.gis.lrg.tum.de/
  :name:  00_img_label

  This is an image caption giving useful information.

  This is an image legend for even more information
  (we won't need this, I assume).

  This text references :numref:`00_image_label` in tow different ways:
  :numref:`My ref text (Abb. %s) <00_img_label>`.

TUM — This is an image caption giving useful information.

This is an image legend for even more information (we won’t need this, I assume).

This text references `00_img_label` in tow different ways: `My ref text %s`.

Todos

Use the following notation to add a todo entry. Todo entries are listed in ToDos.

.. todo:: This describes what needs to be done.

Todo

This describes what needs to be done.

Lists

hlists are more compact bullet lists with a fixed number of columns.

.. hlist::
  :columns: 3

  * item 1
  * more
  * 3rd item
  * 4th item
  * more itmes, nr. 5
  * this is a very long item covering almost an entire line.
  * This item is loooooooooooooooog lllllllllllllllloooooooooooonnnnnnnnnnnnnnggggggg and will use more
    than one liiiiiiiinnnnnnnnnneeeeeeeeeee.

item 1
more
3rd item

4th item
more itmes, nr. 5

this is a very long item covering almost an entire line.
This item is loooooooooooooooog lllllllllllllllloooooooooooonnnnnnnnnnnnnnggggggg and will use more than one liiiiiiiinnnnnnnnnneeeeeeeeeee.