What Is a .RST File?

ReStructuredText document

📂Document

🏷️.rst

🎯text/x-rst

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: john.doe@example.com
: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
     - alice.johnson@company.com
   * - Bob Smith
     - 30
     - Marketing
     - bob.smith@company.com
   * - Carol Davis
     - 28
     - Design
     - carol.davis@company.com

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.