Note
This version of the guide covers the new PHP-based rendering of Documentation with the TYPO3 Documentation theme.
If the project you are looking at has a file Documentation/guides.xml it is using the new rendering.
Otherwise, consider to migrate the Documentation or head over to the legacy version of this guide: How to document, Sphinx based.
Headlines and sections¶
reStructuredText (reST) does not exactly have the notion of "headlines". Text is split into "sections" instead. Those sections are identified by titles which - in the end - appear as headlines as we know them.
TYPO3 uses these conventions.
- Use underlining plus overlining with
===for the first section title of a -
file. The first section title is the "document title" (doctitle) of that file and will appear in the menu. Every .rst file should have a doctitle:
======== DocTitle ========Copied!
- Use underlining plus overlining with
-
Then use underlining only:
1. ========== for the first level 2. ---------- for the second level 3. ~~~~~~~~~~ for the third level 4. """""""""" for the fourth levelCopied! - More levels will be rarely used. For sake of completeness here is the whole
-
hierarchy the automatic conversion tools uses. Stick to this order if more levels are needed:
5. '''''''''' 6. ^^^^^^^^^^ 7. ########## 8. ********** 9. $$$$$$$$$$ 10. `````````` plus: +;.,_/%&! in that orderCopied!
Example¶
========
DocTitle
========
About this document ...
Topic 1
=======
Here we go.
Subtopic 1.1
------------
Here we dive deeper
Subsubtopic 1.1.1
~~~~~~~~~~~~~~~~~
And this is even more specific.
Topic 2
=======
...Syntax¶
Length of Underlines¶
The length of the underlines must at least have the length of the text. It may be longer, not shorter.
Example 1: This Works¶
=========
Example 1
=========Example 2: This Works Too¶
==============
Example 1
==============Example 3: This Does not Work¶
=======
Example 1
=======