reST & Sphinx Cheat Sheet

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.

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

参考

• Headlines and Sections
• Explicit Link Targets (Labels for Cross-Referencing)

Links

External Links

method 1:

Check out more information on t3o.

Source:

Check out more information on `t3o <https://typo3.org>`__.

`anchor text <URL>`__

(with one or two underscores at the end, if in doubt, use two)

method 2: "External Hyperlink Targets"

Check out more information on t3o

source:

Check out more information on t3o_

.. (this is a comment) the link is defined (usually on bottom of page)

.. _t3o: https://typo3.org

This may be more convenient if you use a link several times.

Cross-References

When linking within docs.typo3.org, you should use this method of cross-referencing.

Use it to link to a section in this manual:

:ref:`intersphinx`

A section with the label intersphinx must exist! It is placed before the header:

.. _intersphinx:

Intersphinx
===========

Or, when cross-referencing to other manuals:

:ref:`shortcut:label`

:ref:`h2document:intersphinx`

When you are linking to another manual, make sure the shortcut (here: "h2document") is included in Settings.cfg:

[intersphinx_mapping]

h2document       = https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/Index.html
...

We use the same conventions for naming the shortcuts in Settings.cfg, see Settings.cfg. Not used manuals are commented out.

ちなみに

This is a cool feature, where reST & Sphinx shines: Even when a section is moved to another page (which effectively changes the URL), the link will still work!

	Link to: Same manual	Link to: Other manual
Explicit anchor text	:ref:`Cross Referencing <intersphinx>`	:ref:`Cross Referencing <t3docwrite:intersphinx>`
Automatic anchor text	:ref:`intersphinx`	:ref:`t3docwrite:intersphinx`

参考

• Link Targets (labels)
• Cross-Referencing (:ref:)
• Settings.cfg

Lists

This is a bullet list:

• list item 1
• list item 2

More text.

重要

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!

Add a blank link too, when starting another list hierarchy:

This is a bullet list:

* list item 1

   * list item 1.1
   * list item 1.2

* list item 2

Numbered Lists

重要

Always add blank line before and after list!

some text

1. list item 1
2. list item 2

some text

some text

#. list item 1
#. list item 2

some text

Code Blocks

重要

Use syntactically correct code in your codeblocks.

Code Block Directive

How it looks:

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

Source:

.. code-block:: php

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

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

重要

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

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

: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

Source (image):

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

参考

• Images

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

With Big Numbers XXL

Source:

.. rst-class:: bignums-xxl

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 (Admonitions)

ちなみに

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