| reStructuredText | |
|---|---|
 | |
| Filename extension | .rst |
| Internet media type |
|
| Developed by | David Goodger |
| Initial release | June 1, 2001; 24 years ago (2001-06-01)[1] |
| Latest release | Revision 8407 October 29, 2019; 6 years ago (2019-10-29) |
| Open format? | Public domain |
| Website | docutils |
reStructuredText (RST,ReST, orreST) is a plain-textmarkup language primarily used for technical documentation and other textual data. It serves a similar role asMarkdown but includes additional semantic features for more complex document structuring. Prominent, large-scale, open-source projects that rely on reStructuredText include thePython programming language community for its official documentation, theLinux kernel docs,CMake, and theLLVM compiler project.
It is part of the Docutils project of the Python Doc-SIG (Documentation Special Interest Group), aimed at creating a set of tools for Python similar toJavadoc forJava orPlain Old Documentation (POD) forPerl. Docutils can extract comments and information from Python programs, and format them into various forms of program documentation.[2]
In this sense, reStructuredText is alightweight 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 Pythonsource code.
reStructuredText evolved from an earlier lightweight markup language called StructuredText[3] (developed byZope). There were a number of problems with StructuredText, and reST was developed to address them.[4]The name reStructuredText was chosen to indicate that reST is a "revised, reworked, and reinterpreted StructuredText."[5]
Parts of the reST syntax were inspired by theSetext language from the early 1990s. Elements of the commonRFC822 Internet Message Format andJavadoc formats were also considered for inclusion in the design.[6]
reStructuredText was first released in June 2001.[1] It began to see significant use in the Python community in 2002.[7]
The reference implementation of the reSTparser is a component of the Docutils text processing framework in thePython programming language, but other parsers are available.
The Docutils project has not registered anyMIME type for reStructuredText nor designated any unregistered MIME type as official, but documents the MIME typetext/x-rst as inde facto use by, for example, the build system for the Python website.[8] The same MIME type is used in thefreedesktop.org file type database used bydesktop environments onLinux.[9] Another MIME type,text/prs.fallenstein.rst, was registered as avanity MIME type by a third party in 2003 to represent reStructuredText, and remains the onlyIANA-registered MIME type for reStructuredText,[10] although it is not acknowledged as such by the Docutils project.[8]
reStructuredText is commonly used for technical documentation, for example, in documentation of Python libraries.[11] However, it is suitable for a wide range of texts.
Since 2008, reST has been a core component of Python'sSphinx document generation system.
Trac also supports reStructuredText,[12] as doGitHub andBitbucket.
In 2011,Distributed Proofreaders, which prepared texts forProject Gutenberg, was considering adoption of reST as a basic format from which other ebook formats could be generated.[13][needs update]
In July 2016 theLinux kernel project decided to transition fromDocBook based documentation to reStructuredText and theSphinx toolchain.[14][15][circular reference]
The software build toolCMake switched from a custom markup language to reStructuredText in version 3.0 for its documentation.[16]
| Text using rST syntax | Corresponding HTML produced by an rST processor | Text viewed in a browser |
|---|---|---|
================Document Heading================Heading=======Sub-heading-----------Paragraphs are separated by a blank line. | <h1>Document Heading</h1><h2>Heading</h2><h3>Sub-heading</h3><p>Paragraphs are separatedby a blank line.</p> | Document Heading Heading Sub-heading Paragraphs are separatedby a blank line. |
Text attributes*emphasis*,**strong emphasis**,``monospace``.Horizontal rule:---- | <p>Text attributes<em>emphasis</em>,<strong>strong emphasis</strong>,<code>monospace</code>.</p><p>Horizontal rule:</p><hr/> | Text attributesemphasis,strong emphasis,monospace.Horizontal rule: |
Bullet list:* apples* oranges* pearsNumbered list:1. lather2. rinse3. repeatNested lists:1. fruits* apple* banana2. vegetables* carrot* broccoli | <p>Bullet list:</p><ul><li>apples</li><li>oranges</li><li>pears</li></ul><p>Numbered list:</p><ol><li>lather</li><li>rinse</li><li>repeat</li></ol><p>Nested lists:</p><ol><li>fruits<ul><li>apple</li><li>banana</li></ul></li><li>vegetables<ul><li>carrot</li><li>broccoli</li></ul></li></ol> | Bullet list:
Numbered list:
Nested lists:
|
An`example<http://example.com>`_...image:: Icon-pictures.png:alt: ImageIf text is indented, it is treated as a block quotation, and the final attribution line is handled automatically: Should array indices start at 0 or 1? My suggested compromise of 0.5 was rejected without, I thought, proper consideration. -- Stan Kelly-BootlereST uses :: at the end of the paragraph prior to a pre-formatted code block:: Y = lambda f: (lambda x: f(x(x)))(lambda x: f(x(x)))| Multi-line text can| span in tables| with a pipe character. | <p>An<ahref="http://example.com">example</a>.</p><p><imgalt="Image"src="Icon-pictures.png"/></p><p>If text is indented, it is treated as a block quotation, and the final attribution line is handled automatically:</p><blockquote>Should array indices start at 0 or 1?My suggested compromise of 0.5 was rejected without, I thought, proper consideration.-- Stan Kelly-Bootle</blockquote><p>reST uses :: at the end of the paragraph prior to a pre-formatted code block:</p><preclass="literal-block">Y = lambda f: (lambda x: f(x(x)))(lambda x: f(x(x)))</pre><p>Multi-line text can<br/>span in tables<br/>with a pipe character.</p> | Anexample.
If text is indented, it is treated as a block quotation, and the final attribution line is handled automatically:
reST uses :: at the end of the paragraph prior to a pre-formatted code block: Y = lambda f: (lambda x: f(x(x)))(lambda x: f(x(x))) Multi-line text can |
ReStructuredText was designed and implemented by David Goodger, not by the registrant of this media type. The registrant just happened to have need of a registered media type for it. […] Change control for this registration is currently with Benja Fallenstein. (If anybody more intimately involved with ReStructuredText wants to take it over, it will be surrendered gladly.)
