ReStructuredText

Introduction

ReStructuredText (RST) is a lightweight and straightforward markup used primarily for documentation of software and libraries in the Python programming language community. It is part of the Docutils project of the Python community, which provides a collection of tools for processing plaintext documentation into useful formats, such as HTML, XML, and LaTeX.

A screenshot of a text editor showing a document written in ReStructuredText.

A screenshot of a text editor showing a document written in ReStructuredText.

History

ReStructuredText was developed as a response to the need for a more robust, flexible, and powerful markup language for Python documentation. It was created by David Goodger in 2002 as part of the Docutils project. The language has since been adopted by various other projects and organizations, including the Sphinx documentation generator, which is widely used in the Python community.

Syntax

ReStructuredText uses simple, easy-to-read syntax. It is designed to be easily read in its raw form, yet powerful enough to allow for complex document structure and markup. The language uses a combination of special characters and indentation to denote structure and formatting.

Headers

Headers in ReStructuredText are created by underlining (and optionally overlining) the text with a punctuation character. For example:

.. code-block:: rst

   ==============
   Document Title
   ==============

   Section Header
   --------------

   Subsection Header
   ^^^^^^^^^^^^^^^^^

Paragraphs and Line Breaks

In ReStructuredText, paragraphs are simply blocks of text separated by blank lines. Line breaks within a paragraph are ignored. To create a line break within a paragraph, you can use the "line block" syntax:

.. code-block:: rst

   | This is a line block. It ends with a blank line.
   | This is the second line.

Lists

ReStructuredText supports both unordered (bulleted) and ordered (numbered) lists. List items are marked by hyphens for unordered lists and numbers followed by periods for ordered lists. For example:

.. code-block:: rst

   - Item 1
   - Item 2

   1. Item 1
   2. Item 2

Links

Links in ReStructuredText are created using backticks and underscores. For example, to create a link to the Python website, you would write:

.. code-block:: rst

   `Python <https://www.python.org/>`_

Images

Images can be included in ReStructuredText documents using the ".. image::" directive. For example:

.. code-block:: rst

   .. image:: image.jpg

Advantages and Disadvantages

ReStructuredText offers several advantages over other markup languages. Its syntax is simple and easy to learn, making it accessible to newcomers. It is also highly flexible and extensible, allowing for a wide range of document structures and formatting options.

However, ReStructuredText also has some disadvantages. Its syntax can be verbose compared to other markup languages like Markdown. It also lacks native support for some features common in other markup languages, such as tables. However, these features can often be added through extensions or directives.

Usage

ReStructuredText is widely used in the Python community for writing documentation. It is the default markup language for the Sphinx documentation generator, and is also used in the Python Package Index (PyPI) to format package descriptions.

Outside of the Python community, ReStructuredText is used by various projects and organizations for writing documentation and other types of content. For example, it is used by the GNU Project for their online manuals, and by the Linux Documentation Project for their HOWTOs and guides.

See Also

- Python (programming language) - Docutils - Sphinx (documentation generator) - GNU Project - Linux Documentation Project