Documentation & Markup
reStructuredText (often abbreviated as reST or RST) is a lightweight markup language intended to be both easy to read and easy to write, while also being powerful enough for complex documentation. It is a part of the Python Docutils project, which provides tools to parse and transform reStructuredText into various formats, including HTML, LaTeX, and man pages. reStructuredText is the default markup language for Python's documentation (Sphinx) and is widely used in the open-source community for technical documentation, README files, and inline documentation strings (docstrings). Its design emphasizes the use of plain text that is readable as-is, with a consistent and predictable syntax for headings, lists, links, and other structural elements.
reStructuredText was created by David Goodger as a part of the Docutils project, which he initiated in 2002 to provide a set of tools for processing documentation in Python. The name is a play on "structured text" and the reStructuredText markup is designed to be a clean, extensible, and readable alternative to other lightweight markup languages like Markdown. The specification was first published in 2002 and has remained relatively stable, with the latest version (0.5) released in 2005. Docutils itself continues to be maintained, with version 1.0 released in 2023, and it serves as the foundation for Sphinx, a documentation generator that has become the de facto standard for Python projects and many others.1
reStructuredText uses a simple, whitespace-sensitive syntax that is designed to be readable in plain text. Headings are created by underlining (and optionally overlining) with punctuation characters such as =, -, ~, and ^. Inline markup includes *emphasis*, **strong emphasis**, `interpreted text`, and ``literal text``. Links can be embedded with backticks and underscores, and footnotes and citations are supported. The language also includes directives, which are special blocks that provide additional functionality, such as images, tables, and code blocks. One of its distinctive features is the use of field lists for metadata, and the ability to define custom roles and directives, making it highly extensible.2
reStructuredText is most prominently used as the markup language for Sphinx, which is the standard for Python documentation and is also used by many other projects like Read the Docs. It is also used in Jupyter Notebooks for markdown cells (though Markdown is more common), and in various other tools like Pelican (a static site generator) and Nikola. The language has a dedicated parser in many programming languages, including Python (docutils), JavaScript (marked, though not full support), and Ruby (rdoc). Its adoption is particularly strong in the Python community, where it is used for docstrings and PEPs (Python Enhancement Proposals).3
Beyond its common use in documentation, reStructuredText has several niche features. It supports a "substitution definitions" mechanism that allows you to define reusable snippets of text or images. It also has a "comment" syntax that is not rendered in output. The language is designed to be extensible through "roles" and "directives", which can be added via Python plugins. A lesser-known fact is that reStructuredText is used in the Python standard library's documentation, and it is also the format for PEPs, which are the proposals that guide Python's evolution. Additionally, the Docutils project includes a tool called "rst2html" that can convert reStructuredText to HTML, and it is often used in command-line workflows. The spec also includes a "standalone" mode for creating documents without a full project structure.4
This article is based on the official reStructuredText specification and related documentation.
Help improve the encyclopedia. Reports go straight to the site manager.