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

reStructuredText overview
Directives and roles
Sphinx and Docutils
Tools and editors

Collections

Admonitions
Body elements
Code examples
Images
Inline elements
Lists
Document parts
Semantic elements
Sphinx additions

Elements

admonition
attention
caution
code-block
contents
danger
emphasis
enumerated-list
error
figure
file
hint
image
important
inline image
inline literal
literal-block
note
paragraph
parsed-literal-block
rubric
section
seealso
sidebar
strong emphasis
subscript
substitution
superscript
tip
toctree
topic
transition
warning

Etc.

Contributing

Tools and editors¶

There are plenty of tools for woking with reStructuredText. Also, almost any code editor has reStructuredText files support ranging from simple syntax highlighting to auto-complete, preview, showing errors, linting, etc.

For exahusive list see e.g., https://stackoverflow.com/questions/2746692/restructuredtext-tool-support.

Online preview¶

The Snippets (https://snippets.documatt.com) is online reStructuredText editor can be used to play with the markup and see the results immediately.

Previous: Sphinx and Docutils | Next: Admonitions

On this page

Tools and editors
- Online preview