ReStructuredText - Revision history

imported>Vcfahrenbruck: Added to the intro paragraph, along with some major users for additional context of just how widely used it is.

2025-11-24T05:29:39Z

Added to the intro paragraph, along with some major users for additional context of just how widely used it is.

← Previous revision		Revision as of 05:29, 24 November 2025
Line 4:		Line 4:
	\| name = reStructuredText		\| name = reStructuredText
	\| logo =		\| logo =
	\| icon = [[File:ReStructuredText Logo.svg\|frameless\|reStructuredText logo]]		\| icon = [[File:ReStructuredText Logo.svg\|frameless\|reStructuredText logo\|class=skin-invert]]
	\| iconcaption =		\| iconcaption =
	\| screenshot =		\| screenshot =
Line 29:		Line 29:
	\| url = {{URL\|https://docutils.sourceforge.io/rst.html}}		\| url = {{URL\|https://docutils.sourceforge.io/rst.html}}
	}}		}}
	'''reStructuredText''' ('''RST''', '''ReST''', or '''reST''') is a ~~file format~~ for textual data ~~used primarily in~~ the [[Python programming language]] community for [[~~technical documentation~~]].		'''reStructuredText''' ('''RST''', '''ReST''', or '''reST''') 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 (Documentation Special Interest Group), aimed at creating a set of tools for Python similar to [[Javadoc]] for [[Java (programming language)\|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.<ref>{{cite web		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 (programming language)\|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.<ref>{{cite web
Line 58:		Line 58:
	\| publisher = Docutils Project		\| publisher = Docutils Project
	\| date = 2016-02-26		\| date = 2016-02-26
	\| url = ~~http~~://docutils.sourceforge.net/FAQ.html#why-is-it-called-restructuredtext		\| url = https://docutils.sourceforge.net/FAQ.html#why-is-it-called-restructuredtext
	\| access-date = 2016-10-05		\| access-date = 2016-10-05
	}}</ref>		}}</ref>
Line 86:		Line 86:
	\| title = What's the official MIME type for reStructuredText data? in Docutils FAQ.		\| title = What's the official MIME type for reStructuredText data? in Docutils FAQ.
	\| publisher = Docutils Project		\| publisher = Docutils Project
	\| url = ~~http~~://docutils.sourceforge.net/FAQ.html#what-s-the-official-mime-type-for-restructuredtext-data		\| url = https://docutils.sourceforge.net/FAQ.html#what-s-the-official-mime-type-for-restructuredtext-data
	\| access-date = 2017-12-20 }}</ref> The same MIME type is used in the [[freedesktop.org]] file type database used by [[desktop environment]]s on [[Linux desktop\|Linux]].<ref>{{cite web \|url=https://gitlab.freedesktop.org/xdg/shared-mime-info/-/blob/815b520eb01992a05d41a5434f1227a8be101e15/data/freedesktop.org.xml.in#L6708 \|title=freedesktop.org.xml.in \|work=shared-mime-info \|publisher=[[freedesktop.org]]}}</ref> Another MIME type, {{code\|text/prs.fallenstein.rst}}, was registered as a [[Media type#Personal or vanity tree\|vanity MIME type]] by a third party in 2003 to represent reStructuredText, and remains the only [[IANA]]-registered MIME type for reStructuredText,<ref>{{cite web \|url=https://www.iana.org/assignments/media-types/text/prs.fallenstein.rst \|title=text/prs.fallenstein.rst \|institution=[[IANA]] \|date=2003-10-02 \|first=Benja \|last=Fallenstein \|quotation=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.)}}</ref> although it is not acknowledged as such by the Docutils project.<ref name="docutilsmime"/>		\| access-date = 2017-12-20 }}</ref> The same MIME type is used in the [[freedesktop.org]] file type database used by [[desktop environment]]s on [[Linux desktop\|Linux]].<ref>{{cite web \|url=https://gitlab.freedesktop.org/xdg/shared-mime-info/-/blob/815b520eb01992a05d41a5434f1227a8be101e15/data/freedesktop.org.xml.in#L6708 \|title=freedesktop.org.xml.in \|work=shared-mime-info \|publisher=[[freedesktop.org]]}}</ref> Another MIME type, {{code\|text/prs.fallenstein.rst}}, was registered as a [[Media type#Personal or vanity tree\|vanity MIME type]] by a third party in 2003 to represent reStructuredText, and remains the only [[IANA]]-registered MIME type for reStructuredText,<ref>{{cite web \|url=https://www.iana.org/assignments/media-types/text/prs.fallenstein.rst \|title=text/prs.fallenstein.rst \|institution=[[IANA]] \|date=2003-10-02 \|first=Benja \|last=Fallenstein \|quotation=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.)}}</ref> although it is not acknowledged as such by the Docutils project.<ref name="docutilsmime"/>

Line 287:		Line 287:
	:alt: Image		:alt: Image

	If text is indented, it is treated as a block quotation:		If 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?		Should array indices start at 0 or 1?
Line 304:		Line 304:
	<syntaxhighlight lang="html"><p>An <a href="http://example.com">example</a>.</p>		<syntaxhighlight lang="html"><p>An <a href="http://example.com">example</a>.</p>

	<p><img alt="Image"src="Icon-pictures.png" /></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>		<p>If text is indented, it is treated as a block quotation, and the final attribution line is handled automatically:</p>

imported>Daniel Quinlan: remove background styling that frequently causes unreadable text in dark mode (via WP:JWB)

2024-10-23T01:37:21Z

remove background styling that frequently causes unreadable text in dark mode (via WP:JWB)

New page

{{short description|Lightweight markup language}}
{{distinguish|Representational state transfer}}
{{Infobox file format
| name = reStructuredText
| logo =
| icon = [[File:ReStructuredText Logo.svg|frameless|reStructuredText logo]]
| iconcaption =
| screenshot =
| caption =
| extension = .rst
| mime = {{plainlist|
* text/x-rst
* text/prs.fallenstein.rst}}
| type code =
| uniform type =
| conforms to =
| magic =
| owner = David Goodger
| released = {{Start date and age|2001|06|01}}<ref name="rst-first-release" />
| latest release version = Revision 8407
| latest release date = {{Start date and age|2019|10|29}}
| genre =
| container for =
| contained by =
| extended from =
| extended to =
| standard =
| open = [[Public domain]]
| url = {{URL|https://docutils.sourceforge.io/rst.html}}
}}
'''reStructuredText''' ('''RST''', '''ReST''', or '''reST''') is a file format for textual data used primarily in the [[Python programming language]] community for [[technical documentation]].

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 (programming language)|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.<ref>{{cite web
| last = Mertz
| first = David
| title = XML Matters: reStructuredText
| publisher = IBM developerWorks
| date = 2003-02-01
| url = https://www.ibm.com/developerworks/library/x-matters24/
| access-date = 2016-10-05 }}</ref>

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<ref>{{cite web |title=zope.structuredtext Documentation |url=https://zopestructuredtext.readthedocs.io/en/latest/ |website=Read the Docs |access-date=2022-08-16}}</ref> (developed by [[Zope]]). There were a number of problems with StructuredText, and reST was developed to address them.<ref>{{cite web
| last = Goodger
| first = David
| title = Problems With StructuredText
| publisher = Docutils Project
| date = 2016-05-24
| url = https://docutils.sourceforge.io/docs/dev/rst/problems.html
| access-date = 2022-08-16
}}</ref>
The name reStructuredText was chosen to indicate that reST is a "revised, reworked, and reinterpreted StructuredText."<ref>{{cite web
| last = Goodger
| first = David
| title = Docutils FAQ (Frequently Asked Questions)
| publisher = Docutils Project
| date = 2016-02-26
| url = http://docutils.sourceforge.net/FAQ.html#why-is-it-called-restructuredtext
| access-date = 2016-10-05
}}</ref>

Parts of the reST syntax were inspired by the [[Setext]] language from the early 1990s. Elements of the common [[Email#Internet Message Format|RFC822 Internet Message Format]] and [[Javadoc]] formats were also considered for inclusion in the design.<ref>{{cite web
|last = Goodger
|first = David
|title = A Record of reStructuredText Syntax Alternatives
|publisher = Docutils Project
|url = https://docutils.sourceforge.io/docs/dev/rst/alternatives.html
|website = docutils.sourceforge.io
|access-date = 2022-08-16
|date = 2022-04-02
}}</ref>

reStructuredText was first released in June 2001.<ref name="rst-first-release">{{Cite web |title=Project: reStructuredText - File List |url=https://sourceforge.net/projects/structuredtext/files/restructuredtext/ |url-status=live |archive-url=https://web.archive.org/web/20011019081106/http://sourceforge.net/project/showfiles.php?group_id=7050 |archive-date=19 October 2001 |access-date=5 February 2023 |website=SourceForge}}</ref> It began to see significant use in the Python community in 2002.<ref>{{cite web
| title = Introduction to reStructuredText
| publisher = Write The Docs
| url = https://www.writethedocs.org/guide/writing/reStructuredText/
| access-date = 2022-06-25
}}</ref>

== Reference implementation ==
The reference implementation of the reST [[parser]] is a component of the Docutils text processing framework in the [[Python (programming language)|Python programming language]], but other parsers are available.

The Docutils project has not registered any [[Media type|MIME type]] for reStructuredText nor designated any unregistered MIME type as official, but documents the MIME type <code>text/x-rst</code> as in ''de facto'' use by, for example, the build system for the Python website.<ref name="docutilsmime">{{cite web
| title = What's the official MIME type for reStructuredText data? in Docutils FAQ.
| publisher = Docutils Project
| url = http://docutils.sourceforge.net/FAQ.html#what-s-the-official-mime-type-for-restructuredtext-data
| access-date = 2017-12-20 }}</ref> The same MIME type is used in the [[freedesktop.org]] file type database used by [[desktop environment]]s on [[Linux desktop|Linux]].<ref>{{cite web |url=https://gitlab.freedesktop.org/xdg/shared-mime-info/-/blob/815b520eb01992a05d41a5434f1227a8be101e15/data/freedesktop.org.xml.in#L6708 |title=freedesktop.org.xml.in |work=shared-mime-info |publisher=[[freedesktop.org]]}}</ref> Another MIME type, {{code|text/prs.fallenstein.rst}}, was registered as a [[Media type#Personal or vanity tree|vanity MIME type]] by a third party in 2003 to represent reStructuredText, and remains the only [[IANA]]-registered MIME type for reStructuredText,<ref>{{cite web |url=https://www.iana.org/assignments/media-types/text/prs.fallenstein.rst |title=text/prs.fallenstein.rst |institution=[[IANA]] |date=2003-10-02 |first=Benja |last=Fallenstein |quotation=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.)}}</ref> although it is not acknowledged as such by the Docutils project.<ref name="docutilsmime"/>

== Applications ==
reStructuredText is commonly used for technical documentation, for example, in documentation of Python libraries.<ref>{{cite web
| last=Goodger
| first=David
| title=PEP 287 -- reStructuredText Docstring Format
| date=2002-04-02
| url=https://www.python.org/dev/peps/pep-0287/
| publisher=[[Python Software Foundation]]
| access-date=2016-10-05}}</ref> However, it is suitable for a wide range of texts.

Since 2008, reST has been a core component of Python's [[Sphinx (documentation generator)|Sphinx]] document generation system.

[[Trac]] also supports reStructuredText,<ref>{{cite web
| url=https://trac.edgewall.org/wiki/WikiRestructuredText
| title=reStructuredText Support in Trac
| date=2016-09-13
| publisher=[[Trac]]
| access-date=2016-10-05}}</ref> 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.<ref>{{cite web
| last = Newby
| first = Greg
| title = Minutes of 2010 December 11 meeting
| publisher = Distributed Proofreaders
| date = 2011-01-08
| url = http://www.pgdp.net/phpBB2/viewtopic.php?t=44456
|url-access=registration | access-date = 2011-01-08 }}</ref>{{update inline|date=May 2015}}

In July 2016 the [[Linux kernel]] project decided to transition from [[DocBook]] based documentation to reStructuredText and the [[Sphinx (documentation generator)|Sphinx]] toolchain.<ref>{{cite web
| title = Kernel documentation with Sphinx, part 1: how we got here
| publisher = LWN.net
| date = 2016-07-06
| url = http://lwn.net/Articles/692704/
| access-date = 2016-10-27 }}</ref><ref>{{cite web
| title=Sphinx. Linux kernel
| publisher = Wikipedia
| date = 2024-04-02
| url = https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)#Linux_kernel
| access-date = 2024-04-02}}</ref>{{Circular reference|date=May 2024}}

The software build tool [[CMake]] switched from a custom markup language to reStructuredText in version 3.0 for its documentation.<ref>{{cite web
| title = CMake 3.0.0 Release Notes
| publisher = Kitware, Inc.
| date = 2014-06-10
| url = https://cmake.org/cmake/help/v3.0/release/3.0.0.html
| access-date = 2016-10-05 }}</ref>

== Examples ==
{|class="wikitable"
! width="33%" | Text using rST syntax
! width="34%" | Corresponding HTML produced by an rST processor
! width="33%" | Text viewed in a browser
|-valign="top"
|
<syntaxhighlight lang="rst">
================
Document Heading
================

Heading
=======

Sub-heading
-----------

Paragraphs are separated
by a blank line.
</syntaxhighlight>
|
<syntaxhighlight lang="html">
<h1>Document Heading</h1>

<h2>Heading</h2>

<h3>Sub-heading</h3>

<p>Paragraphs are separated
by a blank line.</p>
</syntaxhighlight>
|<div style="color: #000000; overflow: hidden; page-break-after: avoid;
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</div>

<div style="color: #000000; overflow: hidden; page-break-after: avoid;
font-size: 1.8em; font-family: Georgia,Times,serif; margin-top: 1em; margin-bottom: 0.25em; line-height: 1.3; padding: 0; border-bottom: 1px solid #AAAAAA;>Heading</div>

<div style="color: #000000; overflow: hidden; page-break-after: avoid;
font-size: 1.5em; font-family: Georgia,Times,serif; margin-top: 1em; margin-bottom: 0.25em; line-height: 1.3; padding: 0; border-bottom: 1px solid #AAAAAA;>Sub-heading</div>

Paragraphs are separated
by a blank line.
|-
|<syntaxhighlight lang="rst">Text attributes *emphasis*, **strong emphasis**, ``monospace``.

Horizontal rule:

----
</syntaxhighlight>
|
<syntaxhighlight lang="html"><p>Text attributes <em>emphasis</em>,
<strong>strong emphasis</strong>, <code>monospace</code>.</p>

<p>Horizontal rule:</p>

<hr />
</syntaxhighlight>
|Text attributes ''emphasis'',
'''strong emphasis''', <code>monospace</code>.</p>

Horizontal rule:

<hr />
|-
|<syntaxhighlight lang="rst">
Bullet list:

* apples
* oranges
* pears

Numbered list:

1. lather
2. rinse
3. repeat

Nested lists:

1. fruits

* apple
* banana

2. vegetables

* carrot
* broccoli
</syntaxhighlight>
|
<syntaxhighlight lang="html"><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>

</syntaxhighlight>
|Bullet list:

* apples
* oranges
* pears

Numbered list:

# lather
# rinse
# repeat

Nested lists:
# fruits
#* apple
#* banana
# vegetables
#* carrot
#* broccoli

|-
|<syntaxhighlight lang="rst">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.
</syntaxhighlight>
|
<syntaxhighlight lang="html"><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>
</syntaxhighlight>
|An [http://example.com/ example].

[[File:Icon-pictures.png|alt=Image|link=|icon]]

<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>
|}

== See also ==
* [[Comparison of document markup languages]]
* [[Comparison of documentation generators]]
* [[Comparison of note-taking software]]

==References==

{{Reflist}}

== External links ==
* [https://docutils.sourceforge.io/rst.html Official reStructuredText website with reference pages]

{{lowercase|reStructuredText}}
{{Document markup languages}}

[[Category:Lightweight markup languages]]
[[Category:Source code documentation formats]]