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.

topic

topic is a block with a title and content. Use topic to wrap ideas not strictly related the text, but useful for readers. For example, in the documentation covering authentication, it might be useful to mention that users should choose strong password.

Requires title and content

You need to pass a title after topic:: (note the space after ::), and a content bellow the blank line.

1Nisi occaecat sit reprehenderit incididunt fugiat in sunt. Velit irure et amet aliquip sunt.
2
3.. topic:: Topic title
4
5   Pariatur nulla officia culpa qui commodo cupidatat ea elit aliqua cillum amet elit.
6    
7Dolor adipisicing irure et sit ullamco veniam aliqua. Non laboris duis veniam quis occaecat.

Nisi occaecat sit reprehenderit incididunt fugiat in sunt. Velit irure et amet aliquip sunt.

Topic title

Pariatur nulla officia culpa qui commodo cupidatat ea elit aliqua cillum amet elit.

Dolor adipisicing irure et sit ullamco veniam aliqua. Non laboris duis veniam quis occaecat.

Cannot occur inside body elements or other topic

topic may only occur anywhere a section or transition may occur. Nesting topic inside body element or topic, e.g.:

.. topic:: Topic

   Topic cannot be nested inside body elements or another topic.

   .. topic:: Another topic

      Another topic content.

causes the following error WARNING: The "topic" directive may not be used within topics or body elements.

Directive name in uppercase

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 reStructuredText code readability.

1.. TOPIC::
2
3   Writing topic uppercase can be considered as reasonable exception to "all-lowercase" rule.

Complex content

Any reStructuredText elements can be in topic content. As always, you need only to keep correct indentation.

 1.. topic:: Complex content
 2    
 3   This is the topic with complex body containing
 4
 5   - two items
 6   - bullet list
 7
 8   And, code example::
 9
10       $ nano ~/.bash_aliases

Previous: toctree | Next: transition