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.

tip

tip is one of reStructuredText’s specific 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.

Content on the same line

Short text can be typed right after tip:: (note the space after ::).

1.. tip:: I'm tip

Tip

I’m tip

Content bellow the directive

For longer text more fits to put it the line bellow.

1.. tip::
2   I'm tip

Tip

I’m tip

Content bellow the directive with blank line

Optionally, you can place a blank line before the text itself.

1.. tip::
2
3   I'm tip

Tip

I’m tip

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.. TIP:: However writing admonitions uppercase can be considered as reasonable exception to "all-lowercase" rule.

Tip

However writing admonitions uppercase can be considered as reasonable exception to “all-lowercase” rule.

Complex content

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

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

Tip

This is the admonition with complex body containing

  • two items

  • bullet list

And, code example:

$ nano ~/.bash_aliases

Previous: superscript | Next: toctree