reStructuredText style guide#
This style guide defines Pigweed’s conventions for reStructuredText (reST).
pigweed.dev documentation is authored in reST, not Markdown. Pigweed
uses Sphinx to convert reST into HTML.
Tip
pw format detects reST style issues.
Overview#
Scope#
This style guide applies to all reST markup that’s intended to be published to
pigweed.dev. reST markup is mainly found in .rst files but it’s also
possible to embed reST within other types of files.
Headings#
Use the following syntax for headings.
==================
H1: Document title
==================
In HTML the heading above is rendered as an H1 node. A page must have
exactly one H1 node. The H1 text must have equals signs (``=``) above
and below it.
------------
H2: Sections
------------
In HTML the heading above is rendered as an H2 node. The H2 text must have
minus signs (``-``) above and below it. H2 headings are conceptually similar
to chapters in a book.
H3: Subsections
===============
In HTML the heading above is rendered as an H3 node. The H3 text must
have equals signs (``=``) below it. H3 headings are conceptually similar to
sections within a chapter of a book.
H4: Subsubsections
------------------
In HTML the heading above is rendered as an H4 node. The H4 text must have
minus signs (``-``) below it. H4 headings are used rarely.
H5: Subsubsubsections
^^^^^^^^^^^^^^^^^^^^^
In HTML the heading above is rendered as an H5 node. The H5 text must have
caret symbols (``^``) below it. H5 headings are used very rarely.
H6: Subsubsubsubsections
........................
In HTML the heading above is rendered as an H6 node. The H6 text must have
period symbols (``.``) below it. H6 headings are practically never used and
are an indicator that a document probably needs refactoring.
Heading levels#
Headings must be used in hierarchical order. No level can be skipped. For example, you can’t use an H1 heading followed by an H3. See Headings and titles.
No blank lines after headings#
Don’t put whitespace between a heading and the content that follows it.
Yes
Example heading
===============
This paragraph is positioned correctly.
No
Example heading
===============
This paragraph isn't positioned correctly. There shouldn't be a blank
line above it.
One blank line before a heading#
Put one blank line between a heading and the content that comes before it.
Yes
This paragraph is positioned correctly.
Example heading
---------------
...
No
This paragraph isn't positioned correctly. There's too much whitespace
below it.
Example heading
---------------
...
Directives#
Indent directive content and attributes 3 spaces so that they align with the directive name.
Yes
.. my-directive::
:my-attr: This attribute is positioned correctly.
This paragraph is positioned correctly.
.. my-nested-directive::
This paragraph is positioned correctly.
No
.. my-directive::
This paragraph isn't positioned correctly. It has too few spaces.
.. my-directive::
This paragraph isn't positioned correctly. It has too many spaces.
Put a blank line between the directive and its content. Don’t put space between a directive name and its attributes.
Yes
.. my-directive::
:my-attr: This attribute is positioned correctly.
This paragraph is positioned correctly.
No
.. my-directive::
This paragraph isn't positioned correctly. There should be a blank
line above it.
Tables#
Prefer list-table and csv-table. Avoid table. list-table and
csv-table are easier to maintain.
Code includes#
Prefer including code snippets from actual source code files that are built and tested regularly.
To include a portion of a file:
.. literalinclude:: my_source_file.py
:start-after: my-start-text
:end-before: my-end-text
my-start-text and my-end-text are the exclusive delimiters that must
appear verbatim in the source file.
Python code includes#
Use autodoc.
Python code includes for CLI args#
Use argparse.
Code blocks#
Use code-block. See Languages for the list of valid language keywords.
If Google has a style guide for the programming language in your code block, your code should match Google’s style guide.
.. code-block:: c++
// ...
Table of contents depth customization#
Put :tocdepth: X on the first line of the page, where X equals how many
levels of section heading you want to show in the page’s table of contents. See
//docs/changelog.rst for an example.
Tabs#
Use tab-set and tab-item. See Tabs.
.. tab-set::
.. tab-item:: Linux
Linux instructions...
.. tab-item:: Windows
Windows instructions...
Rendered output:
Linux instructions…
Windows instructions…
Tabs for code-only content#
Use tab-set-code. See Languages for the list of
valid language keywords.
.. tab-set-code::
.. code-block:: c++
// C++ code...
.. code-block:: python
# Python code...
Rendered output:
// C++ code...
# Python code...
Tab synchronization#
Use the :sync: attribute to synchronize tabs for non-code content. See
Rendered output below for an example.
tab-set-code tabs automatically synchronize by code language.
.. tab-set::
.. tab-item:: Linux
:sync: linux
Linux instructions...
.. tab-item:: Windows
:sync: windows
Windows instructions...
.. tab-set::
.. tab-item:: Linux
:sync: linux
More Linux instructions...
.. tab-item:: Windows
:sync: windows
More Windows instructions...
Rendered output:
Linux instructions…
Windows instructions…
More Linux instructions…
More Windows instructions…