reST & Sphinx cheat sheet

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
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
   ========
   DocTitle
   ========

   Then use underlining only:

   .. _header1:

   Header 1
   ========

   Header 1.1
   ----------

   Header 1.1.1
   ~~~~~~~~~~~~

   Header 1.1.1.1
   """"""""""""""
  • 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 3 spaces - including the item sign
  • to create a nested list:
    • indent the items by 3 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 3 spaces - including the item sign
*  to create a nested list:

   *  indent the items by 3 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 3 spaces - including the item sign
  3. to create a nested list:
    1. indent the items by 3 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 3 spaces - including the item sign
#. to create a nested list:

   #. indent the items by 3 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
2
3
4
.. code-block:: php

   $a = 'hello';
   $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 (3 spaces).

Literal Block (::)

Or, use the literal block markup :: if PHP is already set as default with highlight directive and you want to combine a text with a colon, followed by the code block.

How it looks:

Assign the variable a:

$a = 'hello';

Source:

Assign the variable a::

   $a = 'hello';

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
2
3
4
:php:`$result = $a + 23;`
:typoscript:`lib.hello.value = Hello World!`
:file:`/etc/passwd`
: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::

      .. 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::

      .. 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)

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
echo $null >> 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