reStructuredText learning notes

It is only yesterday I noticed some filenames with extension .rst.  Now I know it is reStructuredText.


reStructuredText  - Wikipedia

Filename extension .rst

Developed by David Goodger

Initial release April 2, 2002; 11 years ago

Latest release Revision 7302 / January 3, 2012; 17 months ago

Open format? Public domain

Website docutils.sourceforge.net/docs/ref/rst/restructuredtext.html

The reStructuredText (frequently abbreviated as reST) project is part of the Python programming language Docutils project of the Python Doc-SIG (Documentation Special Interest Group). The goal of the project is to create 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 useful program documentation.[1]

The term reStructuredText is most frequently used to refer to the reST markup format developed by the reST project. In this sense, reST 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

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

There were a number of problems with StructuredText. reST was a re-implementation and extension of the ideas in StructuredText, developed in order to address those problems. The name reStructuredText was chosen to indicate that reST is a "revised, reworked, and reinterpreted StructuredText."

reST began to see significant use in the Python community in 2002. Since 2008, reST has been a core component of Python's Sphinx document generation system.

Reference implementation

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

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

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

Trac supports reStructuredText

Distributed Proofreaders, which prepares texts for Project Gutenberg, is considering adoption of reStructuredText as a basic format from which other ebook formats could be generated.

Examples of reST markup

Headers:

Section Header
==============

Subsection Header
-----------------

Lists:

- A bullet list item

- Second item

  - A sub item

- 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) Sub-sub item

3) Third item

#) Another enumerated list item

#) Second item

Images:

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

Named links:

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:

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

__ http://www.python.org/

Named links and anonymous links enclose text in grave accents (`), and not in apostrophes (').

.END