Coding guidelines for reST files¶
Basic formatting rules¶
Encoding¶
use utf-8
Whitespace and indentation¶
Important
Always use indentation levels correctly. Your code may not be rendered as expected if you do not.
remove white space from the end of lines (= no trailing tabs or spaces)
don't use tabs
one indentation level consists of four spaces
code examples use four spaces as indentation level as well
Note
Currently, the documentation is not always indented consistently. In some manuals, an indentation level of 3 spaces was used instead. We currently recommend to use what has been used on the page you are currently editing.
Example:
1 .. image:: /Images/a4.jpg
2 :alt: Left floating image
3 :target: https://typo3.org
4 :class: with-shadow
lines 2-4 must be indented one level (4 spaces)
Line length¶
Keep lines shorter than 80 characters.
if in doubt about the length: use short lines!
That way reST is readable as source as well
Files can be easily edited directly on GitHub
Files can be compared in a diff view
.editorconfig¶
Most of our documentation projects contain an .editorconfig file.
Use this file to setup your editor / IDE correctly. With some, everything will just work automatically. With others, you will need to download a plugin. This is explained on the Editorconfig page.
Sample contents of .editorconfig
1# EditorConfig is awesome: http://EditorConfig.org
2
3# top-most EditorConfig file? false = no!
4root = false
5
6[{*.rst,*.rst.txt}]
7charset = utf-8
8end_of_line = lf
9insert_final_newline = true
10trim_trailing_whitespace = true
11indent_style = space
12indent_size = 4
13max_line_length = 80
14
15# MD-Files
16[*.md]
17charset = utf-8
18end_of_line = lf
19insert_final_newline = true
20trim_trailing_whitespace = true
21indent_style = space
22indent_size = 4
23max_line_length = 80
This sample .editorconfig will instruct your editor / IDE to:
use utf8 as encoding (line 7)
use spaces instead of tabs (line 11)
use 4 spaces for indenting (line 12)
remove trailing whitespace (line 10)
Special characters¶
The only way to include "special" characters is to use them directly
Headline underlining¶
In reStructuredText it is possible to use any type of underlining. The first used will be recognized as level 1 etc.
However, adhering to the standard for TYPO3 documentation makes it easier for other contributors to find their way around a file and pick the correct underlining for the header level.
Use the conventions as defined in Headlines and sections.
This underlining is used per (.rst) file. It does not matter where in the toctree the file is. You always start with underlining for level 1 (title) in each file:
========
1. Title
========
2. Header Level 1
=================
3. Header Level 2
-----------------
4. Header Level 3
~~~~~~~~~~~~~~~~~
5. Header Level 4
"""""""""""""""""
6. Header Level 5
'''''''''''''''''
7. Header Level 6
^^^^^^^^^^^^^^^^^
8. Header Level 7
#################
etc.
How to add version hints¶
Example, how you can point out deprecations:
.. deprecated:: 10.2
The hook shown here is deprecated since TYPO3 10.2 - use a custom
:ref:`PSR-15 middleware<request-handling>` instead.
New feature:
.. versionadded:: 10.2
Starting with TYPO3 10.2 hooks and signals have been replaced by a PSR-14 based
event dispatching system.
Changes:
.. versionchanged:: 2.3.1
This feature was changed ...
For more information, see the open issue:
Link to changelog¶
Linking to the changelog should not be necessary if all necessary information has been transferred to the documentation, but it is not discouraged either.
The changelog often does not have a title label, so you cannot easily link to it with :ref:
.
You can use the method described in How to link to a changelog:
:doc:`ext_core:Changelog/8.1/Deprecation-75625-DeprecatedCacheClearingOptions`
For this to work, ext_core must be defined in Settings.cfg
:
ext_core = https://docs.typo3.org/c/typo3/cms-core/main/en-us/
Referring to GUI elements¶
If you describe something that needs to be selected from a menu or other GUI element or clicked one after the other, use > as separator and use text role guilabel.
Important
Use the spelling of the word as used in the GUI!
Examples:
Select :guilabel:`File > Open`
- How it looks:
Select File > Open
Click on :guilabel:`ADMIN TOOLS > Extensions` in the backend.
- How it looks:
Click on ADMIN TOOLS > Extensions in the backend.