reStructuredText

From Wikipedia, the free encyclopedia
Jump to navigation Jump to search
reStructuredText
reStructuredText logo
Filename extension
.rst
Internet media typetext/x-rst
Developed byDavid Goodger
Initial releaseApril 2, 2002; 19 years ago (2002-04-02)
Latest release
Revision 8407
(October 29, 2019; 2 years ago (2019-10-29))
Open format?Public domain
Websitedocutils.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 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.[1]

In this sense, reStructuredText is a lightweight markup language designed to be both (a) processable by documentation-processing software such as Docutils, and (b) easily readable by human programmers who are reading and writing Python source code.

History[edit]

There were a number of problems with the earlier lightweight markup language StructuredText (developed by Zope), and reST was developed to address them.[2] The name reStructuredText was chosen to indicate that reST is a "revised, reworked, and reinterpreted StructuredText."[3]

reST began to see significant use in the Python community in 2002.[citation needed]

Reference implementation[edit]

The 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.

There is no official MIME type registered for reStructuredText, but the unofficial one is text/x-rst.[4]

Applications[edit]

reStructuredText is commonly used for technical documentation, for example, in documentation of Python libraries.[5] 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,[6] 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.[7][needs update]

In July 2016 the Linux kernel project decided to transition from DocBook based documentation to reStructuredText and the Sphinx toolchain.[8]

The software build tool CMake switched from a custom markup language to reStructuredText in version 3.0 for its documentation.[9]

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>
Heading
Sub-heading

Paragraphs are separated by a blank line.

 Text attributes *italic*,
**bold**, ``monospace``.

Horizontal rule:

----
<p>Text attributes <em>italic</em>,
<strong>bold</strong>, <code>monospace</code>.</p>

<p>Horizontal rule:</p>

<hr />
Text attributes italic, bold, 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:
  • apples
  • oranges
  • pears

Numbered list:

  1. lather
  2. rinse
  3. repeat

Nested lists:

  1. fruits
    • apple
    • banana
  2. vegetables
    • carrot
    • broccoli
An `example <http://example.com>`.

.. image:: Icon-pictures.png
    :alt: Image
![Image](Icon-pictures.png "icon")

::

    rST uses :: prior to a paragraph
    for blockquoting.
    Multiple paragraphs need to be prepended individually.

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

<blockquote>
<p>rST uses :: prior to a pargraph<br/> for blockquoting.<br/>Multiple paragraphs need to be prepended individually.</p>
</blockquote>

<p>Multi-line text can<br/>span in tables<br/>with a pipe character.</p>
An example.

Image

rST uses :: prior to a paragraph
for blockquoting.
Multiple paragraphs need to be prepended individually.

Multi-line text can
span in tables
with a pipe character.

See also[edit]

References[edit]

  1. ^ Mertz, David (2003-02-01). "XML Matters: reStructuredText". IBM developerWorks. Retrieved 2016-10-05.
  2. ^ Goodger, David (2016-05-24). "reStructuredText: Markup Syntax and Parser Component of Docutils". Docutils Project. Retrieved 2016-10-05.
  3. ^ Goodger, David (2016-02-26). "Docutils FAQ (Frequently Asked Questions)". Docutils Project. Retrieved 2016-10-05.
  4. ^ "What's the official MIME type for reStructuredText data? in Docutils FAQ". Docutils Project. Retrieved 2017-12-20.
  5. ^ Goodger, David (2002-04-02). "PEP 287 -- reStructuredText Docstring Format". Python Software Foundation. Retrieved 2016-10-05.
  6. ^ "reStructuredText Support in Trac". Trac. 2016-09-13. Retrieved 2016-10-05.
  7. ^ Newby, Greg (2011-01-08). "Minutes of 2010 December 11 meeting". Distributed Proofreaders. Retrieved 2011-01-08.
  8. ^ "Kernel documentation with Sphinx, part 1: how we got here". LWN.net. 2016-07-06. Retrieved 2016-10-27.
  9. ^ "CMake 3.0.0 Release Notes". Kitware, Inc. 2014-06-10. Retrieved 2016-10-05.

External links[edit]