Cheat sheet: reST & Sphinx

Headlines

Every reST (.rst) file should use these underlining styles. In reST, you can use different styles in any order you want. These are our conventions for TYPO3 documentation.

 1    ========
 2    DocTitle
 3    ========
 4
 5    Then use underlining only:
 6
 7    ..  _header1:
 8
 9    Header 1
10    ========
11
12    Header 1.1
13    ----------
14
15    Header 1.1.1
16    ~~~~~~~~~~~~
17
18    Header 1.1.1.1
19    """"""""""""""
  • line 1-3: This is the doc title. Every .rst file should have one.

  • line 7: header label. This can be used for cross-referencing to this section:

    :ref:`header1`
    
  • 9-10: Header level 1

  • etc.

Lists

How it looks:

To create a bullet list:

  • add a blank line before and after the list

  • indent the list item text by 4 spaces - including the item sign

  • to create a nested list:

    • indent the items by 4 spaces (left-align with parent item text)

    • apply rules of parent list (blank lines, item text indentation, ..)

More text.

Source:

To create a bullet list:

*   add a blank line before and after the list
*   indent the list item text by 4 spaces - including the item sign
*   to create a nested list:

    *   indent the items by 4 spaces (left-align with parent item text)
    *   apply rules of parent list (blank lines, item text indentation, ..)

More text.

Numbered lists

How it looks:

To create a numbered list:

  1. add a blank line before and after the list

  2. indent the list item text by 4 spaces - including the item sign

  3. to create a nested list:

    1. indent the items by 4 spaces (left-align with parent item text)

    2. apply rules of parent list (blank lines, item text indentation, ..)

More text.

Source:

To create a numbered list:

#.  add a blank line before and after the list
#.  indent the list item text by 4 spaces - including the item sign
#.  to create a nested list:

    #. indent the items by 4 spaces (left-align with parent item text)
    #. apply rules of parent list (blank lines, item text indentation, ..)

More text.

Code Blocks

Important

Use syntactically correct code in your code blocks.

Code block directive

How it looks:

$a = 'hello';
$b = 'something';

Source:

1..  code-block:: php
2
3    $a = 'hello';
4    $b = 'something';

This uses the directive "code-block" (line 1)

Important

Make sure to indent correctly. The lines of the code-block (line 3+) must be indented (4 spaces).

Placeholders

Use the Backus-Naur form like <placeholder-name> for placeholders in code and URLs.

Examples:

  1. class <Entity>Controller extends ActionController

  2. typo3/sysext/core/bin/typo3 impexp:import <file>

  3. https://example.org/typo3/main?token=<token-id>

For XML and HTML, use the comment tag <!-- placeholder-name -->.

Inline code, text roles

For inline code or for other semantic markup of special texts, use text roles.

How it looks:

  1. $result = $a + 23; (PHP snippet)

  2. lib.hello.value = Hello World! (TypoScript snippets)

  3. /etc/passwd (file)

  4. ctrl + s (keyboard strokes)

Source:

1:php:`$result = $a + 23;`
2:typoscript:`lib.hello.value = Hello World!`
3:file:`/etc/passwd`
4:kbd:`ctrl` + :kbd:`s`

Bold & italic

How it looks:

Normal text, bold text and italic text.

Source:

Normal text, **bold text** and *italic text*.

Images

How it looks:

../_images/a4.jpg

Source:

..  image:: /Images/a4.jpg
    :class: with-shadow

Another example:

..  image:: /Images/a4.jpg
    :class: with-shadow
    :target: https://typo3.org
    :alt: alt text
    :width: 100px

See also

YouTube videos

How it looks:

Source:

..  youtube:: wNxO-aXY5Yw

Styled numbered lists

This is often used, for a Quick Start section, involving a few numbered steps:

With Big Numbers

This is an example with a code block (::) embedded in the sections.

How it looks:

  1. Embed an image

    Source:

    /Images/a4.jpg
        :class: with-shadow
    
  2. Two

    Do something else ...

Source:

..  rst-class:: bignums

1.  Embed an image

    Source:

    ..  code-block:: rest

        ..  image: some_image.png
            :class: with-shadow

2.  Two

    Do something else ...

With Big Numbers XXL

How it looks:

  1. Embed an image

    Source:

    /Images/a4.jpg
        :class: with-shadow
    
  2. Two

    Do something else ...

Source:

..  rst-class:: bignums-xxl

1.  Embed an image

    Source:

    ..  code-block:: rest

        ..  image: some_image.png
            :class: with-shadow

2.  Two

    Do something else ...

Configuration values (confval)

How it looks:

title
Required

true

Type

string or LLL reference

Scope

Display

Path

$GLOBALS > TCA > [table] > columns > [field]

The name of the field as shown in the form.

Source:

..  confval:: title

    :Required: true
    :type: string or LLL reference
    :Scope: Display
    :Path: $GLOBALS > TCA > [table] > columns > [field]

    The name of the field as shown in the form.

PHP domain

How it looks:

class Vendor\MyExtension\DateTime

Datetime class

setDate($year, $month, $day)

Set the date.

Parameters
  • $year (int) -- The year.

  • $month (int) -- The month.

  • $day (int) -- The day.

Returns

Either false on failure, or the datetime object for method chaining.

Source:

..  php:namespace::  Vendor\MyExtension

..  php:class:: DateTime

    Datetime class

    ..  php:method:: setDate($year, $month, $day)

        Set the date.

        :param int $year: The year.
        :param int $month: The month.
        :param int $day: The day.
        :returns: Either false on failure, or the datetime object for method chaining.

Tips, hints, important (Admonitions)

Visit Admonitions: Tip, Note, Warning, See also, etc to see the available admonitions.

How it looks:

Tip

To look at the reST source of this rendered page, scroll to the bottom and click on "View page source".

Source:

..  tip::

    To look at the reST source of this rendered page, scroll to the bottom
    and click on "View page source".

Cards

How it looks:

Pages

The Page Management Guide introduces TYPO3's Page Tree and explains how pages are created and managed.

Source:

..  container:: row m-0 p-0

..  container:: col-md-6 pl-0 pr-3 py-3 m-0

    ..  container:: card px-0 h-100

        ..  rst-class:: card-header h3

            ..  rubric:: :ref:`Pages <t3editors:pages>`

        ..  container:: card-body

            The Page Management Guide introduces TYPO3's Page Tree and explains how pages are created and managed.

        ..  container:: card-footer pb-0

            ..  rst-class:: horizbuttons-striking-m

            -  `11 <https://docs.typo3.org/m/typo3/tutorial-editors/11.5/en-us/Pages/Index.html>`__

Tabs

How it looks:

touch example-project-directory/public/FIRST_INSTALL

Source:

..  tabs::

    ..  group-tab:: bash

        ..  code-block:: bash

            touch example-project-directory/public/FIRST_INSTALL

    ..  group-tab:: powershell

        ..  code-block:: powershell

            echo $null >> public/FIRST_INSTALL

Graphs

How it looks:

graph { user [ shape=plaintext; width=4; label="User"; style=""; ] view [ shape=box; width=4; label=<<B>View</B><BR/>Displaying the data>; ] controller [ shape=box; width=4; label=<<B>Controller</B><BR/>Control of functionality>; ] model [ shape=box; width=4; label=<<B>Model</B><BR/>Domain model and domain logic>; ] user -- view -- controller -- model; }

Source:

..  graphviz::

    graph {
        user [
            shape=plaintext;
            width=4;
            label="User";
            style="";
        ]
        view [
            shape=box;
            width=4;
            label=<<B>View</B><BR/>Displaying the data>;
        ]
        controller [
            shape=box;
            width=4;
            label=<<B>Controller</B><BR/>Control of functionality>;
        ]
        model [
            shape=box;
            width=4;
            label=<<B>Model</B><BR/>Domain model and domain logic>;
        ]
        user -- view -- controller -- model;
    }

Diagrams

How it looks:

== Initialization ==

Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

== Repetition ==

Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response

Source:

..  uml::

    == Initialization ==

    Alice -> Bob: Authentication Request
    Bob --> Alice: Authentication Response

    == Repetition ==

    Alice -> Bob: Another authentication Request
    Alice <-- Bob: another authentication Response