Editing ReStructuredText

{{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]]