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

mw-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.

Call-to-action buttons#

Use grid and grid-item-card.

.. grid:: 2

   .. grid-item-card:: :octicon:`<ICON>` <TITLE>
      :link: <REF>
      :link-type: <TYPE>
      :class-item: <CLASS>

      <DESCRIPTION>

  • See Octicons for the list of valid <ICON> values.

  • <REF> can either be a ref or a full URL.

  • <TYPE> must be either ref or url.

  • <CLASS> must be either sales-pitch-cta-primary or sales-pitch-cta-secondary. The top-left or top card should use sales-pitch-cta-primary; all the others should use sales-pitch-cta-secondary. The motivation is to draw extra attention to the primary card.

  • <DESCRIPTION> should be reStructuredText describing what kind of content you’ll see if you click the card.

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…