reStructuredText and Sphinx Reference

Example based gentle reference of the reStructuredText and Sphinx syntax, directives, roles and common issues. It demonstrates almost all the markup making it also good for testing Sphinx themes. Free and open-source.

Table of Contents

Intro

Collections

Elements

Etc.

Contributing

Propose a change

Did you find a typo or bad information? Help by contributing to the project. Fork GitHub repository and propose improvement in a pull request, or file an issue.

File structure

Bellow, you will find project files organization.

On-disk file structure

originals/               diagrams and illustration source files (.afdesign)
source/
    _data/               descriptions (actual content)
        collection/      YAMLs describing collections
        element/         YAMLs descripting elements
        snippets/        YAMLs describing snippets
    _static/             theme overrides
    _templates/          sphinxcontrib.datatemplates' templates (.rst.jinja),
                         Sphinx Theme templates (.html), and
                         description YAML templates (.yaml.jinja)
    element/             RST skeletons for elements
    example/             RST examples that must be open in the
                         the separate page (e.g., examples of sections)
index.rst                master doc
*.rst                    RST collection skeletons

The project uses Sphinx documentation and amazing sphinxcontrib.datatemplates extension.

The project knows only two types of descriptions:

  • a Sphinx element

  • a collection of Sphinx elements

Website is generated from YAML data files and Jinja templates creating RST files. Thanks to Jinja templates, all pages for the same type looks the same.

Important

Data files are expected to have .yaml extension. .yml will cause error.

Skeleton contains no or minimal real content (e.g., only a introduction to a topic). Their purpose is to glue actual descriptions from YAMLs in _data/ into sphinxcontrib.datatemplates’ templates in _templates/.

Elements

Element on the disk comprises:

  • data _data/element/<element-name>.yaml with the content described bellow

  • skeleton elements/<element-name>.rst with content:

    .. datatemplate:yaml:: /_data/element/<element-name>.yaml
   :template: element.rst.jinja

YAML schema for element:

  • title

  • desc

  • collections - element belogs to these collections

  • url

  • list of examples where each contain attributes:

    • name

    • desc

    • source

Example:

title: hint

desc: |
  hint is one of |rst|'s specific :doc:`admonitions </admonitions>`. They are all visually bold blocks often rendered in colors according to their type. Readers will appreciate if you spice up your text with admonitions like this for extra information or to raise their attention.

collections:
  - admonitions
  - body-elements

url: "https://docutils.sourceforge.io/docs/ref/rst/directives.html#specific-admonitions"

examples:
  - name: "Content on the same line"
    desc: "Short text can be typed right after ``hint::`` (note the space after ``::``)."
    source: |
      .. hint:: I'm hint

  - name: Content bellow the directive
    desc: "For longer text more fits to put it the line bellow."
    source: |
      .. hint::
         I'm hint

  - name: Content bellow the directive with blank line
    desc: "Optionally, you can place a blank line before the text itself."
    source: |
      .. hint::

         I'm hint

  - name: Directive name in uppercase
    desc: "Directive name is case insensitive (like all directive and role names). Most documentation and book authors prefer typing directives and roles all in lowercase. However, writing directive name in uppercase corresponds with their “raise attention” objective and improves |rst| code readability."
    source: |
      .. HINT:: However writing admonitions uppercase can be considered as reasonable exception to "all-lowercase" rule.
      
  - name: Complex content
    desc: Any |rst| elements can be in admonition content. As always, you need only to keep correct indentation.
    source: |
      .. hint::
          
         This is the admonition with complex body containing

         - two items
         - bullet list

         And, code example::

             $ nano ~/.bash_aliases

How to add element

  1. Create element description _data/element/<element-name>.yaml. Template is at _templates/element.yaml.jinja.

  2. Add element to collections attribute in YAML. Items are filenames (without suffix) from source/_data/_collection.

  3. Add element to list in _data/collection/<collection-name>.yaml. Items are filenames (without suffix) of element skeleton.

  4. Create element skeleton element/<element-name>.yaml. Template is at _templates/element-skeleton.rst.jinja.

Collections

Collection on the disk comprises:

  • data _data/collection/<collection-name>.yaml with list of elements. Names in the list must exactly correspond to filenames in _data/element/<element>.yaml. E.g.:

    elements:
  - attention
  - caution
  - danger
  - error
  - hint
  - important
  - note
  - tip
  - warning
  - admonition
  - seealso

  • skeleton <collection-name>.rst with content:

    .. datatemplate:json:: /_data/element/<collection-name>.yaml
   :template: collection.rst.jinja

How to add collection

  1. Create collection description _data/collection/<collection-name>.yaml. Template is at _templates/collection.yaml.jinja. Content are elements belonging to it.

  2. Create element skeleton <collection-name>.rst. Template is at _templates/collection-skeleton.rst.jinja.

  3. Add element skeleton to toctree in master document index.rst.

Tips and tricks

Dump variable

If you want to see that is actually in the variable, print it as <pre>. E.g.:

.. raw:: html

   <pre>{{ example.rst }}</pre>

Or, repeat full problematic part:

.. raw:: html

   <pre>
   {% for line in example.rst %}
   {{ line }}
   {% endfor %}
   </pre>

Render to file

Useful for templates debugging.

$ datatemplate render source/_templates/element.rst.jinja source/_data/element/inline-literal.yaml > test.rst

Previous: warning

On this page