reStructuredText (RST, ReST, or reST) is a file format for textual data used primarily in the

Python programming language Python is a high-level, general-purpose programming language. Its design philosophy emphasizes code readability with the use of significant indentation. Python is dynamically-typed and garbage-collected. It supports multiple programming p ...

community for

technical documentation Technical documentation is a generic term for the classes of information created to describe (in technical language) the use, functionality or architecture of a product, system or service. Classes of technical documentation Classes of technical do ...

. 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 Javadoc (originally cased JavaDoc) is a documentation generator created by Sun Microsystems for the Java language (now owned by Oracle Corporation) for generating API documentation in HTML format from Java source code. The HTML format is used for ...

for

Java Java (; id, Jawa, ; jv, ꦗꦮ; su, ) is one of the Greater Sunda Islands in Indonesia. It is bordered by the Indian Ocean to the south and the Java Sea to the north. With a population of 151.6 million people, Java is the world's List ...

Plain Old Documentation Plain Old Documentation (pod) is a lightweight markup language used to document the Perl programming language as well as Perl modules and programs. Design Pod is designed to be a simple, clean language with just enough syntax to be useful. It pur ...

(POD) for

Perl Perl is a family of two high-level, general-purpose, interpreted, dynamic programming languages. "Perl" refers to Perl 5, but from 2000 to 2019 it also referred to its redesigned "sister language", Perl 6, before the latter's name was offici ...

. Docutils can extract comments and information from Python programs, and format them into various forms of program documentation. In this sense, reStructuredText is a

lightweight markup language 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. Lightwei ...

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 In computing, source code, or simply code, is any collection of code, with or without comments, written using a human-readable programming language, usually as plain text. The source code of a program is specially designed to facilitate the wo ...

History

reStructuredText evolved from an earlier lightweight markup language called StructuredText (developed by

Zope 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 methodol ...

). There were a number of problems with StructuredText, and reST was developed to address them. The name reStructuredText was chosen to indicate that reST is a "revised, reworked, and reinterpreted StructuredText." Parts of the reST syntax were inspired by the

Setext Setext (Structure Enhanced Text) is a lightweight markup language used to format plain text documents such as e-newsletters, Usenet postings, and e-mails. In contrast to some other markup languages (such as HTML), the markup is easily readable w ...

language from the early 1990s. Elements of the common RFC822 Internet Message Format and

formats were also considered for inclusion in the design. reST began to see significant use in the Python community in 2002.

Reference implementation

The reference implementation of the reST

parser Parsing, syntax analysis, or syntactic analysis is the process of analyzing a string of symbols, either in natural language, computer languages or data structures, conforming to the rules of a formal grammar. The term ''parsing'' comes from Lat ...

is a component of the Docutils text processing framework in the

, but other parsers are available. There is no official

MIME type A media type (also known as a MIME type) is a two-part identifier for file formats and format contents transmitted on the Internet. The Internet Assigned Numbers Authority, Internet Assigned Numbers Authority (IANA) is the official authority for t ...

registered for reStructuredText, but the unofficial one is text/x-rst.

Applications

reStructuredText is commonly used for technical documentation, for example, in documentation of Python libraries. However, it is suitable for a wide range of texts. Since 2008, reST has been a core component of Python's

Sphinx A sphinx ( , grc, σφίγξ , Boeotian: , plural sphinxes or sphinges) is a mythical creature with the head of a human, the body of a lion, and the wings of a falcon. In Greek tradition, the sphinx has the head of a woman, the haunches of ...

document generation system.

Trac Trac is an open-source, web-based project management and bug tracking system. It has been adopted by a variety of organizations for use as a bug tracking system for both free and open-source software and proprietary projects and products. Tra ...

also supports reStructuredText, as do

GitHub GitHub, Inc. () is an Internet hosting service for software development and version control using Git. It provides the distributed version control of Git plus access control, bug tracking, software feature requests, task management, continuous ...

and

Bitbucket Bitbucket is a Git-based source code repository hosting service owned by Atlassian. Bitbucket offers both commercial plans and free accounts with an unlimited number of private repositories. Services Bitbucket Cloud Bitbucket Cloud (previ ...

. In 2011,

Distributed Proofreaders Distributed Proofreaders (commonly abbreviated as DP or PGDP) is a web-based project that supports the development of e-texts for Project Gutenberg by allowing many people to work together in proofreading drafts of e-texts for errors. As of Marc ...

, which prepared texts for

Project Gutenberg Project Gutenberg (PG) is a Virtual volunteering, volunteer effort to digitize and archive cultural works, as well as to "encourage the creation and distribution of eBooks." It was founded in 1971 by American writer Michael S. Hart and is the ...

, was considering adoption of reST as a basic format from which other ebook formats could be generated. In July 2016 the

Linux kernel The Linux kernel is a free and open-source, monolithic, modular, multitasking, Unix-like operating system kernel. It was originally authored in 1991 by Linus Torvalds for his i386-based PC, and it was soon adopted as the kernel for the GNU ope ...

project decided to transition from

DocBook 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. As a semantic languag ...

based documentation to reStructuredText and the

toolchain. The software build tool

CMake 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 an ...

switched from a custom markup language to reStructuredText in version 3.0 for its documentation.

Examples

References

External links