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.

Table of Contents

Intro

Collections

Elements

Etc.

Code examples

In almost any technical documentation you need to show bits of code, filenames and paths, commands and console examples. They are usually styled in monospace font with optional syntax highlighting.

Block or inline level?

Before continuing, wait a second and thing if you want to show inline or block level code example. Even if you don’t know syntax at this moment, you will understand the difference:

_images/block-vs-inline-code-examples.png

Theme author checklist

If you are developing Sphinx theme, ensure your theme behave properly to wrapping and line numbering long lines.

Code examples wrapping problem:

Code examples wrapping problem fixed:

Long line numbering problem:

_images/linenos-styles-long-lines.png

Previous: Body elements | Next: Images

On this page