ReStructuredText
reStructuredText is a plain-text markup language primarily used for technical documentation and other textual data. It serves a similar role as Markdown but includes additional semantic features for more complex document structuring. Prominent, large-scale, open-source projects that rely on reStructuredText include the Python programming language community for its official documentation, the Linux kernel docs, CMake, and the LLVM compiler project.
It is part of the Docutils project of the Python Doc-SIG, aimed at creating a set of tools for Python similar to Javadoc for Java or Plain Old Documentation for Perl. Docutils can extract comments and information from Python programs, and format them into various forms of program documentation.
In this sense, reStructuredText is a lightweight markup language designed to be both processable by documentation-processing software such as Docutils, and be easily readable by human programmers who are reading and writing Python source code.
History
reStructuredText evolved from an earlier lightweight markup language called StructuredText. There were a number of problems with StructuredText, and reST was developed to address them.The name reStructuredText was chosen to indicate that reST is a "revised, reworked, and reinterpreted StructuredText."
Parts of the reST syntax were inspired by the Setext language from the early 1990s. Elements of the common RFC822 Internet Message Format and Javadoc formats were also considered for inclusion in the design.
reStructuredText was first released in June 2001. It began to see significant use in the Python community in 2002.
Applications
reStructuredText is commonly used for technical documentation, for example, in documentation of Python libraries. However, it is suitable for a wide range of texts.Since 2008, reST has been a core component of Python's Sphinx document generation system.
Trac also supports reStructuredText, as do GitHub and Bitbucket.
In 2011, Distributed Proofreaders, which prepared texts for Project Gutenberg, was considering adoption of reST as a basic format from which other ebook formats could be generated.
In July 2016 the Linux kernel project decided to transition from DocBook based documentation to reStructuredText and the Sphinx toolchain.
The software build tool CMake switched from a custom markup language to reStructuredText in version 3.0 for its documentation.
Examples
Document HeadingHeading=
Sub-heading-----------
Paragraphs are separated
by a blank line.
Document Heading
Heading
Sub-heading
Paragraphs are separated
by a blank line.
font-size: 2em; font-family: Georgia,Times,serif; margin-top: 1em; margin-bottom: 0.25em; line-height: 1.3; padding: 0; border-bottom: 1px solid #AAAAAA;>Document Heading
!["Image"]("Icon-pictures.png")