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.

Sphinx and Docutils

Sphinx and Docutils are two crutial and interconnected tools for technical writing in reStructuredText.


Sphinx ( is a tool that takes reStructuredText files and build a documentation in formats like HTML or PDF. Sphinx is not the only tool that works with the reStructuredText, but is the most advanced and the most used in the industry.

Sphinx also adds few new useful constructs to the reStructuredText, e.g. for creating a table of contents, documenting programming language code. reStructuredText and Sphinx makes a perfect couple.

Sphinx is command-line tool with no graphical interface. Write .rst files in any (plain) text editor you like. Folder with .rst files and Sphinx configuration file is called Sphinx project.

To invoke Sphinx to build a project, do e.g. (on the Linux or macOS):

$ cd my_sphinx_project

$ ls

$ make html

and Sphinx will produce HTML version of the project.


Sphinx is build upon Docutils ( to parse and write documents in reStructuredText text.

Previous: Directives and roles | Next: Tools and editors