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.
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.
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.orgThis 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:`t3writedoc:intersphinx`
When you are linking to another manual, make sure the shortcut (here: “t3write”) is included in Settings.cfg :
[intersphinx_mapping]
t3tsref = https://docs.typo3.org/typo3cms/TyposcriptReference/
t3writedoc = https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/Index.html
Tip
This is a cool feature, where reST & Sphinx shines: Even when a section is moved, 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`
|
See also
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!
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 ¶
Important
Always add blank line before and after list!
some text
- list item 1
- list item 2
some text
some text
#. list item 1
#. list item 2
some text
Code Blocks ¶
Important
Use syntactically correct code in your codeblocks.
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';
Inline Code, Textroles ¶
For inline code or for other semantic markup of special texts, use textroles.
Examples:
-
$result = $a + 23;(PHP snippet) -
lib.hello.value = Hello World!(TypoScript snippets) -
/etc/passwd(file) - ctrl + s (keyboard strokes)
Source (inline text with textroles):
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
See also
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:
-
Embed an image
Source:
../images/a4.jpg :class: with-shadow
-
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:
-
Embed an image
Source:
../images/a4.jpg :class: with-shadow
-
Two
Do something else …
Tips, Hints, Important (Admonitions) ¶
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".