Documentation Contribution Guidelines

The Trusted Firmware-M project uses Sphinx to generate the Official Documentation from Restructed Text .rst source files,

The aim is to align as much as possible with the official Python Documentation Guidelines while keeping the consistency with the already existing files.

The guidance below is provided as a help. It is not meant to be a definitive list.

Overview

The following short-list provides a quick summary of the rules.

List of rules

The following rules should be considered:

  1. H1 document title headers should be expressed by # with over-line (rows on top and bottom) of the text

  2. Only ONE H1 header should allowed per document, ideally placed on top of the page.

  3. H2 headers should be expressed by * with over-line

  4. H2 header’s text should be UNIQUE in per document basis

  5. H3 headers should be expressed by an underline of ‘=’

  6. H4 headers should be expressed by an underline of ‘-‘

  7. H3 and H4 headers have no limitation about naming. They can have similar names on the same document, as long as they have different parents.

  8. H5 headers should be expressed by an underline of ‘^’

  9. H5 headers will be rendered in document body but not in menus on the navigation bar

  10. Do not use more than 5 levels of heading

  11. When writing guides, which are expected to be able to be readable by command line tools, it would be best practice to add long complicated tables, and UML diagrams in the bottom of the page and using internal references(auto-label)

  12. No special formatting should be allowed in Headers (code, underline, strike-through etc)

  13. Long URLs and external references should be placed at the bottom of the page and referenced in the body of the document

  14. New introduced terms and abbreviations should be added to Glossary and directly linked by the :term: notation across all documents using it.

Platform Documentation

The Documentation Build system provides an interface with the platform directory allowing maintainers to bundle platform specific documentation. Platforms are grouped by vendor. This behaviour needs to be explicitly enabled for each vendor’s space by providing the <vendor>/index.rst (responsible for generating the Platform Index File) and adding a table of contents entry for the corresponding vendor’s space. The format and structure of this entry is not strictly defined, and allows flexible control of vendor’s and platform’s documentation space. Follow the Platform Documentation document for more details.

Common Use Cases

The section below describes with examples, a rule compliant implementation for most common documentation elements.

Headers

###################
Document Title (H1)
###################

******************
Chapter Title (H2)
******************

Chapter Section (H3)
====================

Chapter Sub-Section (H4)
------------------------

Subsection of Chapter sub-section (H5)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Code Blocks

The recommendation for code content, is to use the explicit code-block directive, ideally with a defined lexer for the language the block contains.

A list of compatible lexers can be found at Pygments Lexers

.. code-block:: bash

    ls
    pwd

.. code-block:: doscon

    dir

.. code-block:: c

    static struct rn_object_t;

.. code-block:: python3

    print("Hello TF-M")

Restructured Text supports implicit code-blocks by indenting a section of text, surrounded by new lines. While this formatting is allowed, it should be avoided if possible.

The quick brown fox jumps over the lazy dog

    ls
    pwd

Note

Mixing two different code-block formats in the same document will break the whole document’s rendering. When editing an existing document, please follow the existing format.

New documents should always use the explicit format.

Tables

For adding new tables the table:: notation should be used.

.. table:: Components table
   :widths: auto

   +--------------+--------------+-------------+
   | **Title A**  | **Title B**  | **Title C** |
   +==============+==============+=============+
   | Text A       | Text B       | Text C      |
   +--------------+--------------+-------------+

While the equivalent simple table code will render correctly in the output, it will not be added to the index (So it cannot be referenced if needed)

+--------------+--------------+-------------+
| **Title A**  | **Title B**  | **Title C** |
+==============+==============+=============+
| Text A       | Text B       | Text C      |
+--------------+--------------+-------------+

Other types of tables such as list-tables and csv-tables are also permitted, as seen on First Things First and Version 1.0

Reference specific section of a document

In order to reference a specific section of a document, up to level 4 headers (if they are included in the index), the ref: keyword can be used

:ref:`docs/getting_started/tfm_getting_started:Tool & Dependency overview`

This can also be used to quickly scroll to the specific section of the current document. This technique can be used to add complex table in the bottom of a document and create clickable quick access references to it for improved user experience.

Glossary term

For technical terms and abbreviations, the recommended guidance is to add an entry to the Glossary of terms and abbreviations and refer to it, using the term: directive

HAL
Hardware Abstraction Layer
    Interface to abstract hardware-oriented operations and provides a set of
    APIs to the upper layers.

.....

As described in the design document :term:`HAL` abstracts the
hardware-oriented and platform specific
.......

Note

The “:term:” directive does not work when used in special formatting. Using *:term:HAL* will not link to the glossary term.

References

  1. Sphinx

  2. Restructed Text

  3. Python Documentation Guidelines

  4. Pygments Lexers

  5. Intersphinx


Copyright (c) 2020-2023, Arm Limited. All rights reserved.