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.


A picture is worth a thousand words. Generally, pictures in documentation serve two purposes – they are a complement to the text or replace the textual description. Some people learn better with words, others with pictures (or videos).

In documentation, we recognize screenshots which are pictures of a computer screen, or schematic drawings as various diagrams and charts (UML, ERD, flowcharts, …).

Other names for picture are image and figure. Generally, you can use all three interchangeably. However, in reStructuredText, image element is a simple picture, while figure element has a caption, can be numbered, hyperlinked from the text, and is generally suitable for more formal books.


Third type of picture, inline image, is just as a regular image but placed inside a line text and behaves as a inline element.


Previous: Body elements | Next: Inline elements