reStructuredText Style Guide 

General information 

Purpose 

This document intends to define the reStructuredText style-guide.

Add a file to your documentation 

It is possible to explicit create a table of contents over a complete documentation (overall documents) with .. toctree::. For detailed information see How to create table of contents with toctree [4] or check index.rst.

Add your new file to the .. toctree:: of the root index.rst or another rst file. Interesting options are :hidden: to hide the toctree and :glob: to import all files in a folder.

An example for use of .. toctree:: can be found in the ìndex.rst within this porject:

.. toctree::
   :caption: Contents
   :maxdepth: 1

   author
   why.rst
   relation_sphinx_needs
   how-to-write-rst
   sphinx-needs-basics
   architecture-examples
   import_needs
   variant_management
   tickets_example

Table of Contents 

For detailed information see How to create table of contents with contents [5].

With .. contents:: it is possible to create a “table of contents” for the current document.

.. contents:: table of contents

This will be printed like:

Filenames 

We define our filenames only with lowercase alphanumeric characters (a-z, 0-9) and - (minus) symbol.

We use the .rst extension to indicate we defining a reStructuredText file.

Regular text 

Example 1: Regular text

You can write any text,
but please keep in mind,
white       spaces      or new lines are ignored.

If you want to define a new line you can to use line blocks ``|``.
For more information about line blocks please check `How to write lists and line blocks`_.

| ``|`` Here I have defined when a new line has to be printed,
| ``|`` so it looks like how I have specified it.

Or you use an empty line to separate the text

from each other.

You can write any text, but please keep in mind, white spaces or new lines are ignored.

If you want to define a new line you can to use line blocks |. For more information about line blocks please check How to write lists and line blocks [1].

| Here I have defined when a new line has to be printed,

| so it looks like how I have specified it.

Or you use an empty line to separate the text

from each other.

The standard reST inline markup is quite simple, use:

Example 2: reST inline markup

one asterisk: *text* for emphasis (italics),

two asterisks: **text** for strong emphasis (boldface), and

backquotes: ``text`` for code samples.

subscript: H\ :sub:`2`\ O

superscript: E = mc\ :sup:`2`

one asterisk: text for emphasis (italics),

two asterisks: text for strong emphasis (boldface), and

backquotes: text for code samples.

subscript: H₂O

superscript: E = mc²

Alternatives for are subscript and superscript are often the math role ( \(E = mc^2\) ) or literal Unicode characters (H₂O).

For information about inline markup please check How to use inline-markup [3].

Whitespaces 

Indentation 

We indent with 3 spaces. We do not use tabs.

Blank lines 

Blank lines are often need, please think about the description in Regular text. For a better reading in rst, please write two blank lines before overlined sections, i.e. before H1 and H2 and one blank line before other sections. See Headlines for an example.

Comments 

Example 3: Comments

Text before the comment.

.. You can comment with ``..``.

Text after the comment.

Text before the comment.

Text after the comment.

Substitution Definition 

See How to substitute content [12]. It is best practice, to use substitution as less as possible. Often a glossary is better be used.

Example 4: Substitution

.. |reST| replace:: reStructuredText

Yes, |reST| is a long word, anyway I **can** blame anyone for wanting to
abbreviate it. Better use a glossary :).

Yes, reStructuredText is a long word, anyway I can blame anyone for wanting to abbreviate it. Better use a glossary :).

Note

You can use

“image”: can be used for block-level images as well as in a substitution definition for inline images. See even the image example.

“replace”: allows simple macro substitution. It also provides a workaround for the still missing support of nested inline markup.

“unicode”: converts Unicode character codes to characters.

“date”: inserts the current local date.

Headlines 

See reStructuredText Primer - Headlines.

We use the following symbols for the headlines:

Headline level 1. # with overline
Headline level 2. * with overline
Headline level 3. =
Headline level 4. -
Headline level 5. ^
Headline level 6. "

Please define only on H1 for a rst document.

As an example:

##################
H1: document title
##################

Introduction text.


*********
Sample H2
*********

Sample content.


**********
Another H2
**********

Sample H3
=========

Sample H4
---------

Sample H5
^^^^^^^^^

Sample H6
"""""""""

And some more content.

Tables 

The information about tables are wonderful provided in How to write a table [2], https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#tables and https://docutils.sourceforge.io/docs/ref/rst/directives.html#tables .

Grid table syntax 

Especially the handling of bars | within tables has to be acknowledge. They do have to be of sifted to the alignment. So pay attention, a table with malformed middle bares will not reported.

Example 5: Grid table syntax

+------------------------+------------+----------+-----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4  |
| (header rows optional) |            |          |           |
+========================+============+==========+===========+
| body row 1, column 1   | column 2   | column 3 | column 4  |
+------------------------+------------+----------+-----------+
| body row 2             | Cells may span columns.           |
|                        | And with an bar ``|`` in the text |
+------------------------+------------+----------------------+
| body row 3             | Cells may  | - Table cells        |
+------------------------+ span rows. | - contain            |
| body row 4             |            | - body elements.     |
+------------------------+------------+----------------------+

Header row, column 1 (header rows optional)	Header 2	Header 3	Header 4
body row 1, column 1	column 2	column 3	column 4
body row 2	Cells may span columns. And with an bar `\|` in the text
body row 3	Cells may span rows.	Table cells contain body elements.
body row 4	Cells may span rows.	Table cells contain body elements.

Simple tables 

Especially the handling to join adjacent columns has to be acknowledge.

Example 6: Simple tables

=====  =====
   Inputs
------------
  A      B
=====  =====
1      Second column of row 1.
2      Second column of row 2.
       Second line of paragraph.
3      - Second column of row 3.

       - Second item in bullet
         list (row 3, column 2).
\      Row 4; column 1 will be empty.
=====  =====

Inputs
A	B
1	Second column of row 1.
2	Second column of row 2. Second line of paragraph.
3	Second column of row 3. Second item in bullet list (row 3, column 2).
	Row 4; column 1 will be empty.

Table directive 

Example 7: Table directive

.. table:: Truth table for "not"
   :widths: auto
   :align: center

   =====  =====
     A    not A
   =====  =====
   False  True
   True   False
   =====  =====

Table 33 Truth table for “not”
A	not A
False	True
True	False

CSV Table directive 

We want to highlight the directive options file, header and header-rows.

Example 8: csv-table directive

.. csv-table:: Frozen Delights!
   :header: "Treat", "Quantity", "Description"
   :widths: 15, 10, 30

   "Albatross", 2.99, "On a stick!"
   "Crunchy Frog", 1.49, "If we took the bones out,
   it wouldn't be crunchy, now would it?"
   "Gannet Ripple", 1.99, "On a stick!"

Table 34 Frozen Delights!
Treat	Quantity	Description
Albatross	2.99	On a stick!
Crunchy Frog	1.49	If we took the bones out, it wouldn’t be crunchy, now would it?
Gannet Ripple	1.99	On a stick!

List Table directive 

Example 9: list-table directive

.. list-table:: Frozen Delights!
   :widths: 15 10 30
   :header-rows: 1

   * - Treat
     - Quantity
     - Description
   * - Albatross
     - 2.99
     - On a stick!
   * - Crunchy Frog
     - 1.49
     - If we took the bones out, it wouldn't be
       crunchy, now would it?
   * - Gannet Ripple
     - 1.99
     - On a stick!

Table 35 Frozen Delights!
Treat	Quantity	Description
Albatross	2.99	On a stick!
Crunchy Frog	1.49	If we took the bones out, it wouldn’t be crunchy, now would it?
Gannet Ripple	1.99	On a stick!

Lists 

The information about lists are wonderful provided in How to write lists and line blocks [1].

Example 10: Lists and Quote-like blocks

* This is a bulleted list.
* It has two items, the second
  item uses two lines.

1. This is a numbered list.
2. It has two items too.

#. This is a numbered list.
#. It has two items too.

This is a bulleted list.
It has two items, the second item uses two lines.

This is a numbered list.
It has two items too.
This is a numbered list.
It has two items too.

Nested lists are even possible, but be aware that they must be separated from the parent list items by blank lines:

Example 11: Nested lists

* this is
* a list

   * with a nested list
   * and some subitems

* and here the parent list continues

this is
a list
- with a nested list
- and some subitems
and here the parent list continues

Pictures 

Image 

See How to create image [6].

Example 12: Image directive

.. image:: pictures/avatar.png
   :alt: my avatar
   :align: center

Example 13: Image directive inline

|my avatar| greats you.

.. |my avatar| image:: pictures/avatar.png
   :align: top
   :scale: 10%

greats you.

Figure 

See How to create figure [7].

Example 14: Figure directive

.. figure:: pictures/avatar.png
   :scale: 100 %
   :alt: My avatar
   :name: my-avatar

   First line is the caption of the figure (a simple paragraph).

   A legend consists of all elements after the caption.

Fig. 19 First line is the caption of the figure (a simple paragraph).

A legend consists of all elements after the caption.

Math 

The information about mathematical expression are wonderful provided in How to write math [8].

You can use a directive:

Example 15: math directive

.. math::

   (a + b)^2 = a^2 + 2ab + b^2

   (a - b)^2 = a^2 - 2ab + b^2

\[ \begin{align}\begin{aligned}(a + b)^2 = a^2 + 2ab + b^2\\(a - b)^2 = a^2 - 2ab + b^2\end{aligned}\end{align} \]

You can even use inline math role:

Example 16: inline math role

:math:`(a + b)` multiplied with :math:`(a - b)` is equal to :math:`a^2 - b^2`.

\((a + b)\) multiplied with \((a - b)\) is equal to \(a^2 - b^2\).

Source code in the documentation 

We use the code, code-block and literalinclude directive. It is good style to specify the programming language. See How to document code [10].

More sophisticated examples and even a special extension for multilanguage examples can be found under How to document multi language code [11].

code-block 

Example 17: code directive

.. code-block:: rst
   :caption: Example how-to document source code
   :name: Example_Source_Code
   :linenos:

   ##################
   H1: document title
   ##################

.. code:: rst
   :number-lines:

   H2: document title
   ******************

Listing 1 Example how-to document source code

##################
H1: document title
##################

H2: document title
******************

literalinclude 

The literalinclude directive is useful if you want to extract content from a existing file.

Let’s reuse our index.rst file from this project. You can filter for sections, lines, or even show a diff of two files.

Example 18: literalinclude directive

.. literalinclude:: index.rst
   :caption: Example how-to incude source code from a file
   :name: Example_literalinclude
   :language: rst
   :emphasize-lines: 12-20
   :linenos:
   :end-before: Tests

Listing 2 Example how-to incude source code from a file

.. include:: ../README.rst

.. note::

   This project is under active development.


.. toctree::
   :caption: Contents
   :maxdepth: 1

   author
   why.rst
   relation_sphinx_needs
   how-to-write-rst
   sphinx-needs-basics
   architecture-examples
   import_needs
   variant_management
   tickets_example

Indices and tables
******************

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`


.. disabled codeoption as the directive is even disabled

This is often combined with a download link index.rst. Please pay attention, that *.rst files are parsed by sphinx, so may want to use .tmp``for tamplates instead ``.rst.

Often this is combined with a download link to the file, see Links to download files how to achive this.

Links 

Links between parts of the documentation 

Here you can find an example how you link to a reference label (here a headline) in your documentation. The ref is working across rst files. You can find more examples for picture and tables under How to link within a rst documentation [13].

So the starting _ of .. _reSTxt_style_guide_links: defines a start of a reference / anker. And last _ in reSTxt_style_guide_links_ uses this reference / anker.

From this chapter:

.. _reSTxt_style_guide_links:

*****
Links
*****

Example 19: reference to a reference label

If you want to reference to the reference-label, see :ref:`reSTxt_style_guide_links`.
If you want to customize your link text use :ref:`custom text <reSTxt_style_guide_links>`.

If you want to reference to the reference-label, see Links. If you want to customize your link text use custom text.

Note

It is recommended to shorten the link mark as most as possible and use the customized link text way most of the time.

If you only want to link to a headline within a document you can use the headline text itself.

Example 20: Link to headline in the current document

| ... content ...
| I want to link to `References`_.
| ... content ...

… content …
I want to link to References.
… content …

Links to named references 

You can link to named elements like figures, tables, and so on.

Here we link to the above named figure my-avatar.

Example 21: role numref

:ref:`my-avatar`

:ref:`Image of Avatar (Name. '{name}') <my-avatar>`

First line is the caption of the figure (a simple paragraph).

Image of Avatar (Name. ‘{name}’)

If you want to use numref, you have to enable numfig = True in your conf.py. See How to use numref [14].

Example 22: role numref

:numref:`my-avatar`

:numref:`Image of Avatar (Fig. '{number}' and Name. '{name}') <my-avatar>`

Fig. 19

Image of Avatar (Fig. '19' and Name. 'First line is the caption of the figure (a simple paragraph).')

Links to download files 

It is possible to reference to non-rst files, so they can be “downloaded”. For more details please see How to reference to downloadable files [15].

Example 23

Download file to this :download:`file itself <how-to-write-rst.rst>`.

Download file to this file itself.

Reference to document 

It is even possible to reference to a document with :doc:. For more details please see How to reference to file [16].

Example 24: Link to headline in the current document

Reference to this :doc:`file itself <how-to-write-rst>`.

Reference to this file itself.

Include a file into current document 

Docutils documentation: How to include file in document [9].

It is possible to include in the current document another document. Please be aware, that it is useful to have another file extension for included files, standard pattern is .rst.inc. Even files with extension .inc shall not be fetched by the conf.py.

Example of include directive.

.. include:: inclusion.rst.inc

References to external sites 

We can use target-notes to mark often used links to external sites. The approach is used in this file, too. The opportunity is you even get a back link, where in the document this link is been used.

For more details please see How to reference to external web pages [17].

... content ...
If you want to have an example see `How to link within a rst documentation`_.
You can even customize the link `text<How to link within a rst documentation>`_.
... content ...

**********
References
**********

.. target-notes::

_`How to link within a rst documentation`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#hyperlinks

It is even possible to reference directly to an external webside:

Example 25: direct external links

- https://www.sphinx-needs.com
- `sphinx-needs <https://www.sphinx-needs.com>`_

Glossary 

We use glossaries to define often used terms in a documentation. To get more information how to setup a glossary and how to link to, see How to use a glossary [19]. If you want to reference to a glossary entry please use role term.

Example 26: Glossary

.. glossary::

   rst
      Abbreviation of :term:`reStructuredText`.

   reStructuredText
      Markdown language we currently use.

rst: Abbreviation of reStructuredText.
reStructuredText: Markdown language we currently use.

Variants 

See How to use only directive [18].

In the pipeline, we currently set the project_b tag via command line option -t project_b. See .gitlab-ci.yml. Or you could use https://www.sphinx-doc.org/en/master/usage/configuration.html#conf-tags

Example 27: only directive

.. only:: project_a

   We are building currently for Project A.

.. only:: project_b

   We are building currently for Project B.

Warning

Sphinx is always rendering the content inside the only directive, but is discarding the output if not needed. So if you create objects within the only directive, they are available to the datamodel.

Notes, warnings and tips 

We use sphinx build possibility to indicate notes and warnings to user of the documentation. Please keep in mind, that we only use notes and warnings for really important things. For more details please see How to use admonitions [20].

Example 28: note

.. note::

   Note to the user of the documentation.

Note

Note to the user of the documentation.

Example 29: warning

.. warning::

   Warning to the user of the documentation.

Warning

Warning to the user of the documentation.

Example 30: tip

.. tip::

   Tip to the user of the documentation.

Tip

Tip to the user of the documentation.

Open point 

As the complete methodology of Doc-As-Code and the changes we foresee during the transition phase, it is needed to indicate open points in the same way across the work. For this please use todo: in the documentation the start of an open point.

reStructuredText Style Guide 

General information 

Purpose 

References to useful pages 

Add a file to your documentation 

Table of Contents 

Filenames 

Regular text 

Whitespaces 

Indentation 

Blank lines 

Comments 

Substitution Definition 

Headlines 

Tables 

Grid table syntax 

Simple tables 

Table directive 

CSV Table directive 

List Table directive 

Lists 

Pictures 

Image 

Figure 

Math 

Source code in the documentation 

code-block 

literalinclude 

Links 

Links between parts of the documentation 

Links to named references 

Links to download files 

Reference to document 

Include a file into current document 

References to external sites 

Glossary 

Variants 

Notes, warnings and tips 

Open point 

References 