reST & Sphinx Cheat Sheet

Source (header with header label):
.. _rest-cheat-sheet:
=========================
reST & Sphinx Cheat Sheet
=========================

More information:

This is a Header Level 1

Source (header level 1):

This is a Header Level 1
========================

This is a Header Level 2

Source (header level 2):

This is a Header Level 2
------------------------

This is a Header Level 3

Source (header level 3):

This is a Header Level 3
~~~~~~~~~~~~~~~~~~~~~~~~

Lists

This is a bullet list:

  • list item 1
  • list item 2

More text. Important: Always add blank line before and after list!

This is a bullet list:

* list item 1
* list item 2

More text. **Important:** Always add blank line before and after list!

Code Blocks

Code Block Directive

How it looks:

$a = 'hello';

Source:

.. code-block:: php

   $a = 'hello';

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';

Inline Code, Textroles

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

Examples:

  1. $result = $a + 23; (PHP snippet)
  2. lib.hello.value = Hello World! (TypoScript snippets)
  3. /etc/passwd (file)
  4. ctrl + s (keyboard strokes)

Source (inline text with textroles):

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

Bold & Italic

Normal text, bold text and italic text.

Source (bold & italic):

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

Images

../_images/a4.jpg

Source (image):

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

YouTube Videos

Source (YouTube):

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

Source:

.. rst-class:: bignums

1. Embed an image

   Source::

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

2. Two

   Do something else ...

How it looks:

  1. Embed an image

    Source:

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

    Do something else ...

Tips, Hints, Important

Tip

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

Source (tip):
.. tip::

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