Coding guidelines for reStructured text files

In the official documentation files we try to follow the following coding guidelines:

  • Indentation of 4 spaces, this includes lists, directives, Code blocks, and other blocks that need to be indented in ReST.
  • Wrap lines at 80 chars where possible
  • We avoid abbreviations and colloquial language. When we use abbreviations they should be introduced in the same section.
  • Each ReST file must have a main header.
  • Each ReST file must include .. include:: /Includes.rst.txt to display global messages, for example for outdated versions.
  • It is highly recommended to use :navigation-title: My Title at the top of each file to provide a shorter title to be displayed in the menu. See Navigation title: A page title displayed in menus.
Documentation/Introduction.rst 
:navigation-title: Introduction

..  include:: /Includes.rst.txt
..  _introduction:

=====================
Introduction to MyExt
=====================

This extension provides a simple way to display weather data.

*   It fetches data from an external API and processes it in a way that allows
    it to be cached and reused efficiently throughout the TYPO3 site.
*   The results are cached for performance.
*   You can configure the output in the backend.

This extension is compatible with TYPO3 v12 and above.
Copied!

Rules for code examples

  • Wrap code examples at 80 chars where possible to avoid horizontal scrolling.
  • Code examples longer then a few lines should go in external files to be included.
  • All code examples should lint. They should demonstrate best practices. Where best practices would over complicate things, mention that this is not a best practice but used for demonstration.
Documentation/Installation.rst 
:navigation-title: Installation

..  include:: /Includes.rst.txt
..  _installation:

========================================
Installation and usage of this extension
========================================

You can install the extension like this:

..  code-block:: bash

    composer install myvendor/my-extension

..  _config:

Create a configuration file
===========================

If you want to see a more complete configuration, refer to the example below:

..  literalinclude:: _codesnippets/_config.yaml
    :caption: EXT:my_ext/Configuration/MyConfig/config.yaml
Copied!

Rules headlines

  • Headlines are in sentence case.
  • Each headline should be possible to understand without context. This improves search results in the internal search and search engines.
  • Use the official order for marking headlines. The page title is overlined and underlined with =, headlines of level 2 are underlined with =, level 3 with - and level 4 with ~.
  • Each headline should have a unique anchor so that permalinks to the headline can be generated.
..  _rest-cheat-sheet:

=============================
Cheat sheet: reStructuredText
=============================

Some text.

..  _h2-headline:

H2 Headline
===========

Lorem Ipsum

..  _h3-headline:

H3 Headline
-----------

Some more text
Copied!

See Headlines and Anchors for more headline levels.