Example 1: Headings

Headings are indicated by non-alphanumeric characters used as underlines under the section title. These can be any of the following characters: = - ` : ‘ “ ~ ^ _ * + # < >

They must be at least as long as the title itself but typically is just as long as the section title itself.

1.1 Section heading

If you want to have a sub-section within a section, use a different underline character.

1.1.1 Sub-section heading

You can have even more sub-sections with a different character.

1.2 Section heading 2

Using the same underline character as used before by a different section title indicates that the current section is at the same level.

Example 2: Paragraph

We can highlight text in bold or italics. We can also use superscripts such as H ₂ O and superscripts such as E=mc ². Notice that this produces a whitespace between the sub- and superscripts. To avoid the additional whitespace, we have to escape it with the backslash as in H₂O and E=mc²

reStructuredTextr also comes with a substitution mechanism so that we can provide an easy-to-remember alias that will be substituted with the actual reStrcutredText syntax. We use vertical bars to indicate text that should be replaced as in H₂O and E=mc² and then provide definitions for them somewhere in the document (it doesn’t matter if it is at the start or end of the document).

A new paragraph is created by simply adding an empty line between two paragraphs. You can also add a separating horizontal line if you want using four dashes:

---

You may want to quote some text in your documentation. You can insert footnotes using the [1] syntax. You can then define this footnote at the end of your document. Using a leading # sign ensures that footnotes are automatically numbered. If you want to highlight a paragraph visually, for example, to show a quote from an important person, use an indented paragraph. To show a source, leave an empty line between the block quote and the source as shown below.

Important messages by an important person

—Important person [1]

[1] (1,2)

Quote of an important person.

Example 3: Code

To display code on the same line, you can use dashes to highlight code differently from the written text. If you want to show entire code sections, start a new code environment with the .. code:: block (make sure the leave an empty line between this statement and your actual code). You can optionally provide syntax highlighting hints, as well as additional options, such as using line numbers.

Example of code block without syntax highlighting:

#include <iostream>
int main() {
  std::cout << "no syntax highlighting applied" << std::endl;
  return 0;
}

Same code example, but now we use C++ syntax highlighting and line line numbers:

#include <iostream>
int main() {
  std::cout << "c++ syntax highlighting applied" << std::endl;
  return 0;
}

Example 4: Equations

Equations in reStructuredText are rendered by placing a valid LaTeX math expression within a :math: block. For example, the divergence-free constraint of an incompressible flow can be stated as \(\nabla\cdot\mathrm{\mathbf{u}}=0\). We can also display longer equations in their own block using a dedicated math block on a new line (similar to how we used a code block) as:

\[\frac{\partial \mathrm{\mathbf{u}}}{\partial t} + (\mathrm{\mathbf{u}}\cdot\nabla)\mathrm{\mathbf{u}} = -\frac{1}{\rho}\nabla p + \nu \nabla^2\mathrm{\mathbf{u}}\]

We have two options, either we can add an enumerated or an itemised list. Examples of both are given below:

Example 5: Lists

An itemised list may be given as:

• First list item

• Second list item

  • We can have nested items as well, just make sure to leave an empty line between the child and parent item

An enumerated list may be given as:

1. First list item

2. Second list item

3. Can’t be bothered writing out the number, let reStructuredText figure out what number should go at the front

4. More auto numbering

   1. Nested item, use at least 3 leading spaces

Example 6: Tables

We can use two different styles with reStructuredText. Either, we can use the more complete syntax of grid tables or the easier to write, but limited in functionality, simple tables. An example for both is shown below:

Grid table:

Header 1	Header 2	Header 3
body row 1	column 2	column 3
body row 2	Cells may span columns.
body row 3	Cells may span rows.	Cells contain blocks.
body row 4

Simple table:

Inputs		Output
A	B	A or B
False	False	False
True	False	True
False	True	True
True	True	True

Example 7: Links and Images

Links can be added using a description for a website or URL followed by the website itself. Both of these have to be given inside dashes and followed by an underline

Example: Link to cfd.unversity

Images are provided using the image environment and are similar to how we added equations and code. We can, again, provide additional information such as the width of the image and the alternative description (used for screen readers). An example is given below:

Example 8: Badges