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.


Figure is formal more “formal” variant of image used often in academic publications or text books. Unlike the image, it allows to add a caption, be referenced from the other text, etc.

Troubles with backslash

Text inside :file as in all roles, backslashes (\) are maybe treat differently than you expect.

Because backslash is the escaping character. Backslash alone escape immediatelly following character, e.g. the space. To use backslash, you must escaped it too, which results in doubled backslash.

1Not escaped backslashes:
4Properly escaped:

Not escaped backslashes: C:UsersmattAppData

Properly escaped: C:\Users\matt\AppData

Previous: figure | Next: hint