ReStructuredText

Last updated
reStructuredText
ReStructuredText Logo.svg
Filename extension
.rst
Internet media type
  • text/x-rst
  • text/prs.fallenstein.rst
Developed byDavid Goodger
Initial releaseJune 1, 2001;23 years ago (2001-06-01) [1]
Latest release
Revision 8407
October 29, 2019;4 years ago (2019-10-29)
Open format? Public domain
Website 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.

Contents

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. [2]

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 [3] (developed by Zope). There were a number of problems with StructuredText, and reST was developed to address them. [4] The name reStructuredText was chosen to indicate that reST is a "revised, reworked, and reinterpreted StructuredText." [5]

Parts of the reST syntax were inspired by the Setext language from the early 1990s. Elements of the common RFC822 Internet Message Format and Javadoc formats were also considered for inclusion in the design. [6]

reStructuredText was first released in June 2001. [1] It began to see significant use in the Python community in 2002. [7]

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.

The Docutils project has not registered any MIME type for reStructuredText nor designated any unregistered MIME type as official, but documents the MIME type text/x-rst as in de facto use by, for example, the build system for the Python website. [8] The same MIME type is used in the freedesktop.org file type database used by desktop environments on Linux. [9] Another MIME type, text/prs.fallenstein.rst, was registered as a vanity MIME type by a third party in 2003 to represent reStructuredText, and remains the only IANA-registered MIME type for reStructuredText, [10] although it is not acknowledged as such by the Docutils project. [8]

Applications

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

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

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

Examples

Text using rST syntaxCorresponding HTML produced by an rST processorText 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>
Document Heading
Heading
Sub-heading

Paragraphs are separated by a blank line.

Text attributes *emphasis*, **strong emphasis**, ``monospace``.  Horizontal rule:  ---- 
<p>Text attributes <em>emphasis</em>, <strong>strong emphasis</strong>, <code>monospace</code>.</p><p>Horizontal rule:</p><hr/>
Text attributes emphasis, strong emphasis, 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  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. 
<p>An <ahref="http://example.com">example</a>.</p><p><imgalt="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><preclass="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>
An example.

Icon-pictures.png

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

See also

Related Research Articles

Zope is a family of free and open-source web application servers written in Python, and their associated online community. Zope stands for "Z Object Publishing Environment", and was the first system using the now common object publishing methodology for the Web. Zope has been called a Python killer app, an application that helped put Python in the spotlight.

DocBook is a semantic markup language for technical documentation. It was originally intended for writing technical documents related to computer hardware and software, but it can be used for any other sort of documentation.

<span class="mw-page-title-main">KDevelop</span> Integrated development environment

KDevelop is a free and open-source integrated development environment (IDE) for Unix-like computer operating systems and Windows. It provides editing, navigation and debugging features for several programming languages, and integration with build automation and version-control systems, using a plugin-based architecture.

YAML is a human-readable data serialization language. It is commonly used for configuration files and in applications where data are being stored or transmitted. YAML targets many of the same communications applications as Extensible Markup Language (XML) but has a minimal syntax that intentionally differs from Standard Generalized Markup Language (SGML). It uses Python-style indentation to indicate nesting and does not require quotes around most string values.

<span class="mw-page-title-main">Doxygen</span> Free software for generating software documentation from source code

Doxygen is a documentation generator and static analysis tool for software source trees. When used as a documentation generator, Doxygen extracts information from specially-formatted comments within the code. When used for analysis, Doxygen uses its parse tree to generate diagrams and charts of the code structure. Doxygen can cross reference documentation and code, so that the reader of a document can easily refer to the actual code.

<span class="mw-page-title-main">Graphviz</span> Software package for graph visualization

Graphviz is a package of open-source tools initiated by AT&T Labs Research for drawing graphs specified in DOT language scripts having the file name extension "gv". It also provides libraries for software applications to use the tools. Graphviz is free software licensed under the Eclipse Public License.

A lightweight markup language (LML), also termed a simple or humane markup language, is a markup language with simple, unobtrusive syntax. It is designed to be easy to write using any generic text editor and easy to read in its raw form. Lightweight markup languages are used in applications where it may be necessary to read the raw document as well as the final rendered output.

<span class="mw-page-title-main">SCons</span>

SCons is a computer software build tool that automatically analyzes source code file dependencies and operating system adaptation requirements from a software project description and generates final binary executables for installation on the target operating system platform. Its function is analogous to the traditional GNU build system based on the make utility and the autoconf tools.

A chemical file format is a type of data file which is used specifically for depicting molecular data. One of the most widely used is the chemical table file format, which is similar to Structure Data Format (SDF) files. They are text files that represent multiple chemical structure records and associated data fields. The XYZ file format is a simple format that usually gives the number of atoms in the first line, a comment on the second, followed by a number of lines with atomic symbols and cartesian coordinates. The Protein Data Bank Format is commonly used for proteins but is also used for other types of molecules. There are many other types which are detailed below. Various software systems are available to convert from one format to another.

The following tables compare general and technical information for a number of document markup languages. Please see the individual markup languages' articles for further information.

<span class="mw-page-title-main">Markdown</span> Plain text markup language

Markdown is a lightweight markup language for creating formatted text using a plain-text editor. John Gruber created Markdown in 2004 as an easy to read markup language. Markdown is widely used for blogging and instant messaging, and also used elsewhere in online forums, collaborative software, documentation pages, and readme files.

Ddoc is a compiler-embedded documentation generator and associated syntax, for the D programming language, designed by Walter Bright. Its emphasis is on being able to write documentation in code comments in a natural style, minimizing the need for embedded markup and thus improving the legibility of the code comments. It is similar in concept to Doxygen and Javadoc.

In programming, a docstring is a string literal specified in source code that is used, like a comment, to document a specific segment of code. Unlike conventional source code comments, or even specifically formatted comments like docblocks, docstrings are not stripped from the source tree when it is parsed and are retained throughout the runtime of the program. This allows the programmer to inspect these comments at run time, for instance as an interactive help system, or as metadata.

<span class="mw-page-title-main">CMake</span> Cross-platform, compiler-independent build system generator

In software development, CMake is cross-platform free and open-source software for build automation, testing, packaging and installation of software by using a compiler-independent method. CMake is not a build system itself; it generates another system's build files. It supports directory hierarchies and applications that depend on multiple libraries. It can invoke native build environments such as Make, Qt Creator, Ninja, Android Studio, Apple's Xcode, and Microsoft Visual Studio. It has minimal dependencies, requiring only a C++ compiler on its own build system.

In information and communications technology, a media type, content type or MIME type is a two-part identifier for file formats and format contents. Their purpose is comparable to filename extensions and uniform type identifiers, in that they identify the intended data format. They are mainly used by technologies underpinning the Internet, and also used on Linux desktop systems.

<span class="mw-page-title-main">Comment (computer programming)</span> Explanatory note in the source code of a computer program

In computer programming, a comment is a programmer-readable explanation or annotation in the source code of a computer program. They are added with the purpose of making the source code easier for humans to understand, and are generally ignored by compilers and interpreters. The syntax of comments in various programming languages varies considerably.

JSDoc is a markup language used to annotate JavaScript source code files. Using comments containing JSDoc, programmers can add documentation describing the application programming interface of the code they're creating. This is then processed, by various tools, to produce documentation in accessible formats like HTML and Rich Text Format. The JSDoc specification is released under CC BY-SA 3.0, while its companion documentation generator and parser library is free software under the Apache License 2.0.

Sphinx is a documentation generator written and used by the Python community. It is written in Python, and also used in other environments.

Pydoc is the standard documentation module for the programming language Python. Similar to the functionality of Perldoc within Perl and Javadoc within Java, Pydoc allows Python programmers to access Python's documentation help files, generate text and HTML pages with documentation specifics, and find the appropriate module for a particular job.

References

  1. 1 2 "Project: reStructuredText - File List". SourceForge. Archived from the original on 19 October 2001. Retrieved 5 February 2023.
  2. ↑ Mertz, David (2003-02-01). "XML Matters: reStructuredText". IBM developerWorks . Retrieved 2016-10-05.
  3. ↑ "zope.structuredtext Documentation". Read the Docs. Retrieved 2022-08-16.
  4. ↑ Goodger, David (2016-05-24). "Problems With StructuredText". Docutils Project. Retrieved 2022-08-16.
  5. ↑ Goodger, David (2016-02-26). "Docutils FAQ (Frequently Asked Questions)". Docutils Project. Retrieved 2016-10-05.
  6. ↑ Goodger, David (2022-04-02). "A Record of reStructuredText Syntax Alternatives". docutils.sourceforge.io. Docutils Project. Retrieved 2022-08-16.
  7. ↑ "Introduction to reStructuredText". Write The Docs. Retrieved 2022-06-25.
  8. 1 2 "What's the official MIME type for reStructuredText data? in Docutils FAQ". Docutils Project. Retrieved 2017-12-20.
  9. ↑ "freedesktop.org.xml.in". shared-mime-info. freedesktop.org.
  10. ↑ Fallenstein, Benja (2003-10-02). "text/prs.fallenstein.rst". IANA. 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.)
  11. ↑ Goodger, David (2002-04-02). "PEP 287 -- reStructuredText Docstring Format". Python Software Foundation . Retrieved 2016-10-05.
  12. ↑ "reStructuredText Support in Trac". Trac. 2016-09-13. Retrieved 2016-10-05.
  13. ↑ Newby, Greg (2011-01-08). "Minutes of 2010 December 11 meeting" . Distributed Proofreaders. Retrieved 2011-01-08.
  14. ↑ "Kernel documentation with Sphinx, part 1: how we got here". LWN.net. 2016-07-06. Retrieved 2016-10-27.
  15. ↑ "Sphinx. Linux kernel". Wikipedia. 2024-04-02. Retrieved 2024-04-02.
  16. ↑ "CMake 3.0.0 Release Notes". Kitware, Inc. 2014-06-10. Retrieved 2016-10-05.
This page is based on this Wikipedia article
Text is available under the CC BY-SA 4.0 license; additional terms may apply.
Images, videos and audio are available under their respective licenses.