reStructuredText (RST, ReST, or reST) is a file format for textual data used primarily in the Python programming language community for technical documentation.
 | |
| Filename extension |
.rst |
|---|---|
| Internet media type |
|
| Developed by | David Goodger |
| Initial release | June 1, 2001[1] |
| Latest release | Revision 8407 October 29, 2019 |
| Open format? | Public domain |
| Website | docutils |
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 to Javadoc for Java or Plain Old Documentation (POD) for Perl. Docutils can extract comments and information from Python programs, and format them into various forms of program documentation.[2]
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
editreStructuredText evolved from an earlier lightweight markup language called StructuredText[3] (developed by Zope). 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 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.[6]
reStructuredText was first released in June 2001.[1] It began to see significant use in the Python community in 2002.[7]
Reference implementation
editThe reference implementation of the reST parser is a component of the Docutils text processing framework in the Python programming language, but other parsers are available.
The Docutils project has not registered any MIME type for reStructuredText nor designated any unregistered MIME type as official, but documents the MIME type text/x-rst as in de facto use by, for example, the build system for the Python website.[8] The same MIME type is used in the freedesktop.org file type database used by desktop environments on Linux.[9] Another MIME type, text/prs.fallenstein.rst, was registered as a vanity MIME type by a third party in 2003 to represent reStructuredText, and remains the only IANA-registered MIME type for reStructuredText,[10] although it is not acknowledged as such by the Docutils project.[8]
Applications
editreStructuredText 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's Sphinx document generation system.
Trac also supports reStructuredText,[12] 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.[13][needs update]
In July 2016 the Linux kernel project decided to transition from DocBook based documentation to reStructuredText and the Sphinx toolchain.[14][15][circular reference]
The software build tool CMake switched from a custom markup language to reStructuredText in version 3.0 for its documentation.[16]
Examples
edit| 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 separated
by a blank line.</p>
|
Paragraphs are separated by 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 attributes emphasis,
strong emphasis, monospace.
Horizontal rule: |
Bullet list:
* apples
* oranges
* pears
Numbered list:
1. lather
2. rinse
3. repeat
Nested lists:
1. fruits
* apple
* banana
2. 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: Image
If text is indented, it is treated as a block quotation:
Should array indices start at 0 or 1?
My suggested compromise of 0.5 was rejected without, I thought, proper consideration.
-- Stan Kelly-Bootle
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
| span in tables
| with a pipe character.
|
<p>An <a href="http://example.com">example</a>.</p>
<p><img alt="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>
<pre class="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>
|
An example.
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 |
See also
editReferences
edit- ^ a b "Project: reStructuredText - File List". SourceForge. Archived from the original on 19 October 2001. Retrieved 5 February 2023.
- ^ Mertz, David (2003-02-01). "XML Matters: reStructuredText". IBM developerWorks. Retrieved 2016-10-05.
- ^ "zope.structuredtext Documentation". Read the Docs. Retrieved 2022-08-16.
- ^ Goodger, David (2016-05-24). "Problems With StructuredText". Docutils Project. Retrieved 2022-08-16.
- ^ Goodger, David (2016-02-26). "Docutils FAQ (Frequently Asked Questions)". Docutils Project. Retrieved 2016-10-05.
- ^ Goodger, David (2022-04-02). "A Record of reStructuredText Syntax Alternatives". docutils.sourceforge.io. Docutils Project. Retrieved 2022-08-16.
- ^ "Introduction to reStructuredText". Write The Docs. Retrieved 2022-06-25.
- ^ a b "What's the official MIME type for reStructuredText data? in Docutils FAQ". Docutils Project. Retrieved 2017-12-20.
- ^ "freedesktop.org.xml.in". shared-mime-info. freedesktop.org.
- ^ Fallenstein, Benja (2003-10-02). "text/prs.fallenstein.rst". IANA.
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.)
- ^ Goodger, David (2002-04-02). "PEP 287 -- reStructuredText Docstring Format". Python Software Foundation. Retrieved 2016-10-05.
- ^ "reStructuredText Support in Trac". Trac. 2016-09-13. Retrieved 2016-10-05.
- ^ Newby, Greg (2011-01-08). "Minutes of 2010 December 11 meeting". Distributed Proofreaders. Retrieved 2011-01-08.
- ^ "Kernel documentation with Sphinx, part 1: how we got here". LWN.net. 2016-07-06. Retrieved 2016-10-27.
- ^ "Sphinx. Linux kernel". Wikipedia. 2024-04-02. Retrieved 2024-04-02.
- ^ "CMake 3.0.0 Release Notes". Kitware, Inc. 2014-06-10. Retrieved 2016-10-05.
External links
edit