User:lsloan/ReStructuredText

reStructuredText
Filename extension	.rst
Developed by	David Goodger
Initial release	April 2, 2002; 22 years ago (2002-04-02)
Latest release	Revision 7629 March 11, 2013; 11 years ago (2013-03-11)
Free format?	Public domain
Website	docutils.sourceforge.net/docs/ref/rst/restructuredtext.html

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

reStructuredText is sometimes abbreviated as RST, ReST, or reST. This can create confusion with Representational State Transfer (REST), an unrelated technology.

History edit

Setext (developed by Ian Feldman or Tony Sanders) and StructuredText (developed by Zope) were ancestral forms of lightweight markup language.

There were a number of problems with StructuredText, 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.

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.

Applications edit

reStructuredText is commonly used for technical documentation, for example, in documentation of Python libraries.^[4] However, it is suitable for a wide range of texts.

Since 2008, reST is a core component of Python's Sphinx document generation system.

Trac also supports reStructuredText,^[5] as does GitHub and Bitbucket.

Distributed Proofreaders, which prepares texts for Project Gutenberg, is considering adoption of reST as a basic format from which other ebook formats could be generated.^[6]^{[needs update]}

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

Examples of reST markup edit

Headers edit

reST	Generated HTML (http://rst.ninjs.org/)
Section Header ============== Subsection Header -----------------	<h1 class="title">Section Header</h1> <h2 class="subtitle" id="subsection-header">Subsection Header</h2>

reST	Generated HTML (http://rst.ninjs.org/)

Lists edit

reST	Generated HTML (http://rst.ninjs.org/)
- A bullet list item - Second item - A sub item - Spacing between items creates separate lists - Third item 1) An enumerated list item 2) Second item a) Sub item that goes on at length and thus needs to be wrapped. Note the indentation that must match the beginning of the text, not the enumerator. i) List items can even include paragraph breaks. 3) Third item #) Another enumerated list item #) Second item	<ul class="simple"> <li>A bullet list item</li> <li>Second item<ul> <li>A sub item</li> </ul> </li> <li>Spacing between items creates separate lists</li> <li>Third item</li> </ul> <ol class="arabic"> <li><p class="first">An enumerated list item</p> </li> <li><p class="first">Second item</p> <ol class="loweralpha"> <li><p class="first">Sub item that goes on at length and thus needs to be wrapped. Note the indentation that must match the beginning of the text, not the enumerator.</p> <ol class="lowerroman"> <li><p class="first">List items can even include</p> <p>paragraph breaks.</p> </li> </ol> </li> </ol> </li> <li><p class="first">Third item</p> </li> <li><p class="first">Another enumerated list item</p> </li> <li><p class="first">Second item</p> </li> </ol>

reST

Generated HTML (http://rst.ninjs.org/)

- A bullet list item
- Second item

  - A sub item

- Spacing between items creates separate lists

- Third item

1) An enumerated list item

2) Second item

   a) Sub item that goes on at length and thus needs
      to be wrapped. Note the indentation that must
      match the beginning of the text, not the 
      enumerator.

      i) List items can even include

         paragraph breaks.

3) Third item

#) Another enumerated list item

#) Second item

<ul class="simple">
<li>A bullet list item</li>
<li>Second item<ul>
<li>A sub item</li>
</ul>
</li>
<li>Spacing between items creates separate lists</li>
<li>Third item</li>
</ul>
<ol class="arabic">
<li><p class="first">An enumerated list item</p>
</li>
<li><p class="first">Second item</p>
<ol class="loweralpha">
<li><p class="first">Sub item that goes on at length and thus needs
to be wrapped. Note the indentation that must
match the beginning of the text, not the
enumerator.</p>
<ol class="lowerroman">
<li><p class="first">List items can even include</p>
<p>paragraph breaks.</p>
</li>
</ol>
</li>
</ol>
</li>
<li><p class="first">Third item</p>
</li>
<li><p class="first">Another enumerated list item</p>
</li>
<li><p class="first">Second item</p>
</li>
</ol>

Images edit

.. image:: /path/to/image.jpg

Named links edit

A sentence with links to Wikipedia_ and the `Linux kernel archive`_.

.. _Wikipedia: http://www.wikipedia.org/
.. _Linux kernel archive: http://www.kernel.org/

Anonymous links edit

Another sentence with an `anonymous link to the Python website`__.

__ https://www.python.org/

N.B.: named links and anonymous links are enclosed in grave accents (`), and not in apostrophes (').

Literal blocks edit

::

  some literal text

This may also be used inline at the end of a paragraph, like so::

  some more literal text

.. code:: python

   print("A literal block directive explicitly marked as python code")

References edit

^ Mertz, David (2003-02-01). "XML Matters: reStructuredText". IBM developerWorks. Retrieved 2011-12-28.
^ Goodger, David (2006-09-22). "reStructuredText: Markup Syntax and Parser Component of Docutils". Docutils Project. Retrieved 2008-06-11.
^ Goodger, David (2008-01-05). "Docutils FAQ (Frequently Asked Questions)". Docutils Project. Retrieved 2008-06-25.
^ Goodger, David. "reStructuredText Docstring Format". PFS. Retrieved 18 Jan 2009.
^ http://trac.edgewall.org/wiki/WikiRestructuredText
^ Newby, Greg (2011-01-08). "Minutes of 2010 December 11 meeting". Distributed Proofreaders. Retrieved 2011-01-08.
^ "CMake 3.0.0 Release Notes". Kitware, Inc. 2014-06-10. Retrieved 2014-07-09.

External links edit

Category:Lightweight markup languages