About RST Files

reStructuredText

Released 2002 By David Goodger

RST (reStructuredText) is a lightweight markup language used in Python documentation.

Family

Documents & Text

Extension

.rst

MIME Type

text/x-rst

Can Use As

Input Output

The story

HOW RST
CAME TO BE.

2002

2008

reStructuredText was created by David Goodger in 2002 as part of the Docutils project, which aimed to provide a lightweight text markup for Python documentation. Python’s Python Enhancement Proposal (PEP) system adopted RST; Sphinx, launched in 2008 by Georg Brandl, built a rich documentation generator on top of RST that became the standard for Python project docs — Python’s own docs, NumPy, SciPy, Django, Flask, requests, most major Python projects.

RST’s syntax is denser than Markdown but more structured: cross-references work out of the box, auto-generated table of contents, admonitions (note, warning, tip), code blocks with language hinting, and a rich directive system for complex elements. For a decade Python documentation was synonymous with Sphinx-rendered RST. In recent years Markdown + MyST has eroded some of RST’s dominance even in the Python world, but RST remains the canonical format for Python PEPs and most foundational libraries.

CURIOSITIES &
TRIVIA.

Every Python PEP (Python Enhancement Proposal) since 2002 has been written in RST — the language's entire governance documentation.

Sphinx, built on RST by Georg Brandl in 2008, renders the official Python documentation at docs.python.org.

RST supports "directives" (`.. note::`, `.. warning::`) — a plugin system for custom rich content.

The `Read the Docs` hosting platform, built on Sphinx, hosts tens of thousands of open-source Python projects rendered from RST.

RST cross-reference targets — `:ref:\`label\``, `:doc:\`../other\`` — let long technical docs have clickable internal links without a separate URL scheme.

STRENGTHS &
LIMITATIONS.

Strengths

Rich directives for admonitions, code, math, and custom elements.
Cross-references work within and across documents.
Sphinx ecosystem offers best-in-class Python docs output.
Standardized as part of Python PEP infrastructure.
Plain text, version-controllable.

Limitations

Syntax denser than Markdown — higher learning curve.
Less widely adopted than Markdown outside Python world.
Multiple directive dialects (Sphinx, Docutils, custom) create fragmentation.
MyST (Markdown + Sphinx) has pulled many Python projects toward Markdown.

Typical Sizes & Weights

API reference page

5-50 KB

Sphinx project chapter

20-100 KB

Full library documentation

500 KB - 10 MB

Technical Specifications

MIME type: text/x-rst
Extension: .rst
Toolchain: Docutils, Sphinx, Read the Docs
Encoding: UTF-8
Related formats: MyST (Markdown + RST directives)

CONVERT FROM
RST

rst pdf rst docx rst odt rst txt rst md rst html rst epub rst adoc rst org rst textile rst mediawiki rst man rst opml rst t2t rst dokuwiki rst jira rst creole rst muse

CONVERT TO
RST

md rst html rst docx rst txt rst odt rst tex rst epub rst htm rst xhtml rst adoc rst org rst textile rst mediawiki rst man rst opml rst typst rst t2t rst dokuwiki rst jira rst creole rst muse rst doc rst rtf rst xml rst djvu rst pages rst srt rst vtt rst ass rst ssa rst ps rst sub rst json rst yaml rst toml rst mobi rst azw3 rst fb2 rst lit rst cbz rst cbr rst htmlz rst txtz rst pdb rst lrf rst snb rst

Common Use Cases

Python docs, Sphinx projects