reStructuredText File Format

Overview

reStructuredText (RST) is a lightweight markup language primarily used for technical documentation in the Python ecosystem. Created by David Goodger in 2002 as part of the Docutils project, RST provides a readable, unobtrusive syntax that can be processed into various output formats including HTML, PDF, LaTeX, and man pages.

Technical Details

• MIME Type: text/x-rst
• File Extension: .rst
• Category: Document
• First Appeared: 2002
• Parser: Docutils (Python)
• Paradigm: Lightweight markup language

Structure and Syntax

reStructuredText uses indentation and special characters to define document structure, similar to other markup languages but with unique conventions.

Basic Document Structure

=====================================
Document Title (Top-Level Heading)
=====================================

:Author: John Doe
:Date: 2025-06-14
:Version: 1.0

.. contents:: Table of Contents
   :depth: 2

Introduction
============

This is the introduction section. reStructuredText supports **bold text**, 
*italic text*, and ``inline code``.

Chapter 1: Getting Started
==========================

Section 1.1: Basic Concepts
----------------------------

Subsection 1.1.1: Details
~~~~~~~~~~~~~~~~~~~~~~~~~~

This is a subsection with some content.

Conclusion
==========

This concludes our document.

Headings and Structure

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

Chapter Title
=============

Section Title
-------------

Subsection Title
~~~~~~~~~~~~~~~~

Sub-subsection Title
^^^^^^^^^^^^^^^^^^^^

Paragraph Title
"""""""""""""""

# Alternative heading styles (using overlines)
################
 Document Title
################

*************
Chapter Title
*************

Section Title
=============

Text Formatting

Basic Text Formatting
=====================

This is normal text with **bold text** and *italic text*.

You can also use ``inline code`` and create hyperlinks like this:
`Python <https://python.org>`_.

Special characters need escaping: \*, \`, \\.

Substitution references work like this: |date| or |version|.

.. |date| replace:: 2025-06-14
.. |version| replace:: 1.0.0

Here's a line block for preserving line breaks:

| Line 1 of the poem
| Line 2 of the poem
| Line 3 of the poem

Block quotes are indented:

    This is a block quote. It can span multiple lines
    and is useful for highlighting important text or
    quotes from other sources.

Lists and Tables

Lists

Lists and Enumerations
======================

Bullet Lists
------------

* First item
* Second item with sub-items:

  * Sub-item A
  * Sub-item B

    * Nested sub-item

* Third item

Numbered Lists
--------------

1. First numbered item
2. Second numbered item

   a. Sub-item with letters
   b. Another sub-item

      i. Roman numeral sub-item
      ii. Another roman numeral

3. Third numbered item

Definition Lists
----------------

Term 1
    Definition of term 1.

Term 2
    Definition of term 2, which can be quite long
    and span multiple lines.

Field Lists
-----------

:Author: John Doe
:Email: [email protected]
:Date: 2025-06-14
:Status: Draft

Tables

Tables
======

Simple Tables
-------------

====== ====== ========
Name   Age    Location
====== ====== ========
Alice  25     New York
Bob    30     London  
Carol  28     Tokyo   
====== ====== ========

Grid Tables
-----------

+------------+------------+-----------+
| Header 1   | Header 2   | Header 3  |
+============+============+===========+
| Row 1,     | Row 1,     | Row 1,    |
| Col 1      | Col 2      | Col 3     |
+------------+------------+-----------+
| Row 2,     | Row 2,     | Row 2,    |
| Col 1      | Col 2      | Col 3     |
+------------+------------+-----------+

List Tables
-----------

.. list-table:: Employee Information
   :header-rows: 1
   :widths: 20 10 30 40

   * - Name
     - Age
     - Department
     - Email
   * - Alice Johnson
     - 25
     - Engineering
     - [email protected]
   * - Bob Smith
     - 30
     - Marketing
     - [email protected]
   * - Carol Davis
     - 28
     - Design
     - [email protected]

CSV Tables
----------

.. csv-table:: Sales Data
   :header: "Quarter", "Sales", "Growth"
   :widths: 15, 10, 10

   "Q1 2025", "$10,000", "5%"
   "Q2 2025", "$12,000", "12%"
   "Q3 2025", "$15,000", "15%"

Code and Technical Content

Code Blocks

Code Examples
=============

Inline Code
-----------

Use ``print("Hello, World!")`` to display text.

Code Blocks
-----------

Here's a simple Python example::

    def greet(name):
        return f"Hello, {name}!"
    
    print(greet("World"))

Syntax Highlighted Code
----------------------

.. code-block:: python
   :linenos:
   :emphasize-lines: 3,4

   def fibonacci(n):
       """Generate Fibonacci sequence up to n."""
       a, b = 0, 1
       while a < n:
           yield a
           a, b = b, a + b
   
   # Generate first 10 Fibonacci numbers
   fib_sequence = list(fibonacci(100))
   print(fib_sequence)

.. code-block:: javascript
   :caption: JavaScript Example

   function calculateArea(radius) {
       return Math.PI * radius * radius;
   }
   
   const area = calculateArea(5);
   console.log(`Circle area: ${area}`);

Include External Files
---------------------

.. literalinclude:: example.py
   :language: python
   :lines: 1-10
   :linenos:

Mathematical Content

Mathematics and Formulas
========================

Inline Math
-----------

The quadratic formula is :math:`x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}`.

Block Math
----------

.. math::

   \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}

.. math::
   :label: euler

   e^{i\pi} + 1 = 0

This is Euler's famous identity, shown in equation :eq:`euler`.

Complex Formulas
----------------

.. math::

   \begin{align}
   \nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} &= \frac{4\pi}{c}\vec{\mathbf{j}} \\
   \nabla \cdot \vec{\mathbf{E}} &= 4 \pi \rho \\
   \nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} &= \vec{\mathbf{0}} \\
   \nabla \cdot \vec{\mathbf{B}} &= 0
   \end{align}

Directives and Extensions

Admonitions

Admonitions and Warnings
========================

.. note::
   This is a note admonition. It's used to highlight
   important information that readers should be aware of.

.. warning::
   This is a warning admonition. Use it to alert readers
   about potential issues or pitfalls.

.. danger::
   This is a danger admonition for critical warnings
   that could cause serious problems.

.. tip::
   This is a tip admonition for helpful suggestions
   and best practices.

.. important::
   This highlights particularly important information
   that shouldn't be overlooked.

.. seealso::
   Related links and references:
   
   * `Python Documentation <https://docs.python.org/>`_
   * `Sphinx Documentation <https://www.sphinx-doc.org/>`_

Custom Admonition
-----------------

.. admonition:: Custom Title
   :class: custom-style

   You can create custom admonitions with your own titles
   and styling classes.

Images and Media

Images and Media
================

Simple Image
------------

.. image:: path/to/image.png
   :alt: Alternative text
   :width: 300px
   :height: 200px

Figure with Caption
-------------------

.. figure:: path/to/diagram.png
   :align: center
   :scale: 75%
   :alt: System architecture diagram

   Figure 1: System Architecture Overview
   
   This diagram shows the overall architecture of our system,
   including the main components and their interactions.

Image with Alignment
-------------------

.. image:: path/to/logo.png
   :align: right
   :width: 150px

This text will wrap around the image on the left side
because the image is aligned to the right.

Substitution Images
------------------

You can use substitution references for images: |logo|

.. |logo| image:: path/to/logo.png
   :width: 100px

Cross-References and Links

Cross-References and Links
==========================

Internal References
-------------------

See the section on `Basic Document Structure`_ above.

You can also create explicit targets:

.. _custom-target:

Custom Target Section
~~~~~~~~~~~~~~~~~~~~~

This section can be referenced as custom-target_.

External Links
--------------

Visit `Python.org <https://python.org>`_ for more information.

You can also use anonymous references: `Python documentation`__

.. __: https://docs.python.org/

Footnotes
---------

This text has a footnote [1]_ and another one [#label]_.

.. [1] This is a numbered footnote.
.. [#label] This is a labeled footnote.

You can also use auto-numbered footnotes [#]_ and [#]_.

.. [#] First auto-numbered footnote.
.. [#] Second auto-numbered footnote.

Citations
---------

According to [Smith2020]_, the results show significant improvement.

.. [Smith2020] Smith, J. (2020). Advanced Topics in Computer Science.
   Journal of Computing, 15(3), 123-145.

Advanced Features

Sphinx Extensions

Sphinx-Specific Features
=======================

API Documentation
-----------------

.. automodule:: mymodule
   :members:
   :undoc-members:
   :show-inheritance:

.. autoclass:: MyClass
   :members:
   :inherited-members:

.. autofunction:: my_function

Toctree (Table of Contents Tree)
-------------------------------

.. toctree::
   :maxdepth: 2
   :caption: Contents:
   :numbered:
   :titlesonly:

   introduction
   installation
   tutorial/index
   api/index
   faq

Index Entries
-------------

.. index:: 
   single: Python; programming
   pair: API; documentation
   triple: Sphinx; reStructuredText; documentation

This paragraph will be indexed under the specified terms.

Glossary
--------

.. glossary::

   API
      Application Programming Interface

   REST
      Representational State Transfer

   JSON
      JavaScript Object Notation

You can reference glossary terms like :term:`API` or :term:`REST`.

Custom Directives

Advanced Directives
==================

Downloads
---------

.. download:: example.py

Version Information
------------------

.. versionadded:: 1.2.0
   This feature was added in version 1.2.0.

.. versionchanged:: 1.3.0
   The behavior of this function changed significantly.

.. deprecated:: 1.4.0
   This function is deprecated. Use :func:`new_function` instead.

Todo Items
----------

.. todo::
   Implement error handling for edge cases.

.. todo::
   Add unit tests for the new feature.

Production List (for Grammar)
-----------------------------

.. productionlist::
   statement: expression ";"
   expression: term (("+" | "-") term)*
   term: factor (("*" | "/") factor)*
   factor: "(" expression ")" | number

Documentation Workflow

Sphinx Project Structure

Project Structure
================

A typical Sphinx project has this structure::

    myproject/
    ├── source/
    │   ├── conf.py          # Configuration file
    │   ├── index.rst        # Main document
    │   ├── _static/         # Static files (CSS, images)
    │   ├── _templates/      # Custom templates
    │   └── modules/         # Additional RST files
    ├── build/               # Generated output
    └── requirements.txt     # Python dependencies

Configuration Example
--------------------

Here's a sample ``conf.py`` configuration:

.. code-block:: python

   # Configuration file for Sphinx documentation

   project = 'My Project'
   copyright = '2025, John Doe'
   author = 'John Doe'
   release = '1.0.0'

   extensions = [
       'sphinx.ext.autodoc',
       'sphinx.ext.viewcode',
       'sphinx.ext.napoleon',
       'sphinx.ext.intersphinx',
   ]

   templates_path = ['_templates']
   exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

   html_theme = 'sphinx_rtd_theme'
   html_static_path = ['_static']

   intersphinx_mapping = {
       'python': ('https://docs.python.org/3', None),
   }

Build Commands

# Initialize new Sphinx project
sphinx-quickstart

# Build HTML documentation
sphinx-build -b html source build/html

# Build PDF documentation
sphinx-build -b latex source build/latex
cd build/latex && make

# Watch for changes and auto-rebuild
sphinx-autobuild source build/html

# Check for broken links
sphinx-build -b linkcheck source build/linkcheck

Best Practices

Writing Guidelines

Writing Best Practices
======================

Document Structure
-----------------

1. **Use consistent heading levels**: Start with a single top-level
   heading and maintain hierarchy.

2. **Provide clear navigation**: Use table of contents and 
   cross-references liberally.

3. **Write descriptive headings**: Make headings self-explanatory
   and searchable.

Content Guidelines
-----------------

* **Be concise but complete**: Provide necessary information without
  unnecessary verbosity.

* **Use active voice**: Write "Configure the server" instead of 
  "The server should be configured."

* **Include examples**: Show concrete examples for abstract concepts.

* **Maintain consistency**: Use consistent terminology and formatting
  throughout the document.

Technical Writing
----------------

.. code-block:: rst

   # Good: Clear, specific heading
   Installing Python Dependencies
   =============================

   # Poor: Vague heading
   Setup
   =====

   # Good: Descriptive code example
   .. code-block:: python
      :caption: Database connection example

      import sqlite3
      conn = sqlite3.connect('example.db')

   # Poor: Code without context
   .. code-block:: python

      import sqlite3

Formatting Standards

• Use 3 spaces for indentation in list items
• Keep lines under 80 characters when possible
• Use blank lines to separate sections
• Be consistent with punctuation in lists
• Use semantic markup (emphasis for importance, not just styling)

Tools and Integration

Documentation Tools

• Sphinx: Primary documentation generator
• Read the Docs: Hosting platform for documentation
• Pandoc: Universal document converter
• restview: Live preview for RST files
• rstcheck: RST syntax checker

IDE and Editor Support

• Visual Studio Code: RST extensions available
• PyCharm: Built-in RST support
• Vim: RST syntax highlighting plugins
• Emacs: rst-mode for editing
• Sublime Text: RST packages available

Integration Examples

# Python docstring using RST
def calculate_area(radius):
    """Calculate the area of a circle.
    
    :param float radius: The radius of the circle
    :returns: The area of the circle
    :rtype: float
    :raises ValueError: If radius is negative
    
    Example:
        >>> calculate_area(5.0)
        78.53981633974483
    """
    if radius < 0:
        raise ValueError("Radius cannot be negative")
    return 3.14159 * radius ** 2

Common Use Cases

Software Documentation

• API documentation with Sphinx autodoc
• User manuals and tutorials
• Development guides and contributing guidelines
• Release notes and changelogs

Academic and Technical Writing

• Research papers and theses
• Technical specifications
• Standard operating procedures
• Educational materials and textbooks

Project Documentation

• README files for open source projects
• Installation and configuration guides
• Architecture and design documents
• Troubleshooting and FAQ sections

reStructuredText continues to be the preferred choice for Python project documentation and technical writing, offering a perfect balance of readability in source form and rich formatting capabilities in output formats.