Last Updated on March 19, 2024
reStructuredText (often abbreviated as reST) is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. It’s designed to be a simple, unobtrusive markup language.
This lightweight markup language is useful for in-line program documentation (such as Python docstrings), technical documentation, for quickly creating simple web pages, as well as standalone documents.
reStructuredText is part of the Docutils project. The purpose of the project is to create a set of tools for processing reStructuredText documentation into useful formats, such as HTML, LaTeX, ODT or Unix manpages. Docutils can extract comments and information from Python programs, and format them into various forms of useful program documentation.
All reST files use an indentation of 3 spaces; no tabs are allowed. The maximum line length is 80 characters for normal text, but tables, deeply indented code samples and long links may extend beyond that.
The reference implementation of the reST parser is a component of the Docutils text processing framework.
The name of the language derives from two other markup languages, Setext and StructuredText.
reStructuredText is the default plaintext markup language used by Sphinx.
Ways to Learn reStructuredText
The RestructuredText Book Documentation
By (Daniel Greenfeld, Eric Holscher PDF; 27 pages)
This is a syntax guide designed to provide very clear, understandable examples and tutorials of reST usage. It borrows information from several sources.
The incomplete guide covers the basics of the language, and block quotes. It then offers a tutorial and guide to Sphinx. A few sections are yet to be published.
Cheat Sheet – a refresher for this markup language.
A ReStructuredText Primer – an informal introduction to reST.
| Advantages | Disadvantages | ||
|---|---|---|---|
 | Readable and simple to learn syntax |  | Syntax can seem strange at times |
| Popular in the Python community | | Confusing output from compiler |
| Often used for technical documentation | | Limited support from editors and other types of software |
| Extensibility - provides standard extension mechanisms called directives and roles | | Not as rich as DocBook XML |
| Designed to offer most of the same features as LaTeX | ||
Useful Software for reST
pandoc – converts files from one markup format into another.
Docutils – an open-source text processing system for processing plaintext documentation into useful formats, such as HTML, LaTeX, man-pages, open-document or XML. It includes reStructuredText.
Formiko – a reStructuredText and MarkDown editor and live previewer. It’s written in Python with Gtk3, GtkSourceView and Webkit2.
Pelican – a static site generator, written in Python, that requires no database or server-side logic.