README: Docutils 1.0b1.dev

Author:: David Goodger
Contact:: goodger@python.org
Date:: 2026-06-11
Web site:: https://docutils.sourceforge.io/
Copyright:: This document has been placed in the public domain.

Abstract

Docutils is a modular system for processing documentation into useful formats, such as HTML, XML, and LaTeX. For input Docutils supports reStructuredText, an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax.

Quick-Start

This is for those who want to get up & running quickly.

Docutils requires Python, available from https://www.python.org/. See Dependencies below for details.
Install the latest stable release from PyPi with pip:
```
pip install docutils
```
For alternatives and details, see section Installation below.
Use the front-end scripts to convert reStructuredText documents. Try for example:
```
docutils FAQ.rst FAQ.html
```
See Usage below for details.

Purpose

The purpose of the Docutils project is to provide a set of tools for processing plaintext documentation into useful formats, such as HTML, LaTeX, troff (man pages), OpenOffice, and native XML. Support for the following sources has been implemented:

Standalone files.
PEPs (Python Enhancement Proposals).

Support for the following sources is planned or provided by third party tools:

Inline documentation from Python modules and packages, extracted with namespace context.
Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).
Wikis, with global reference lookups of "wiki links".
Compound documents, such as multiple chapter files merged into a book.
And others as discovered.

Dependencies

To run the code, Python must be installed. (Python is pre-installed with most Linux distributions.)

Since version 0.21, Docutils requires Python 3.9 or later.
Docutils versions 0.19 to 0.20.1 require Python 3.7 or later.
Docutils versions 0.16 to 0.18 require Python 2.7 or 3.5+.

The type hints added in version 0.22 use Python 3.10 syntax. However, the Python interpreter treats them as annotations unless typing.TYPE_CHECKING is set to True.

Recommendations

Docutils uses the following packages for enhanced functionality, if they are installed:

The recommended installer is pip, setuptools works, too.
The Python Imaging Library (PIL) is used for some image manipulation operations.
The Pygments package provides syntax highlight of "code" directives and roles.
The myst or pycmark parsers can be used to parse input in "Markdown" (CommonMark) format.

The Docutils Link List records projects that users of Docutils and reStructuredText may find useful.

Installation

The Python Packaging User Guide gives details how to use pip for installing.

The simplest way is to install the latest stable release from PyPi:
```
pip install docutils
```
To install a pre-relase, append the option --pre.
To install a development version from source:
1. Open a shell
2. Go to the directory containing the pyproject.toml file.
3. Install the package with one of the following commands:
```
pip install -e .  # editable install
pip install .     # regular install
```
  or do a "manual" install.
4. Optional steps:
  - Running the test suite
  - Converting the documentation
See also the OS-specific installation instructions below and the Docutils version repository documentation.
To install for a specific Python version, use this version in the setup call, e.g.
```
python3.11 -m pip install docutils
```
If the python executable isn't on your path, you'll have to specify the complete path, such as /usr/local/bin/python3.11.

To install for different Python versions, repeat step 3 for every required version. The last installed version will be used for the docutils command line application.

GNU/Linux, BSDs, Unix, Mac OS X, etc.

Use su or sudo for a system-wide installation as root, e.g.:
```
sudo pip install docutils
```

Windows

The Python FAQ explains how to run a Python program under Windows.
Usually, pip is automatically installed if you are using Python downloaded from https://python.org. If not, see the pip documentation.
The command window should recognise the word py as an instruction to start the interpreter, e.g.

py -m pip install docutils

If this does not work, you may have to specify the full path to the Python executable.

Usage

Start the "docutils" command line application with:

docutils [options] [<source> [<destination>]]

The default action is to convert a reStructuredText document to HTML5, for example:

docutils test.rst test.html

Read the --help option output for details on options and arguments and Docutils Front-End Tools for the full documentation of the various tools.

For programmatic use of the docutils Python package, read the API Reference Material and the source code. Remaining questions may be answered in the Docutils Project Documentation or the Docutils-users mailing list.

Contributions are welcome!

Project Files & Directories

README.rst: You're reading it.
COPYING.rst: Public Domain Dedication and copyright details for non-public-domain files (most are PD).
FAQ.rst: Frequently Asked Questions (with answers!).
RELEASE-NOTES.rst: Summary of the major changes in recent releases.
HISTORY.rst: A detailed change log, for the current and all previous project releases.
BUGS.rst: Known bugs, and how to report a bug.
THANKS.rst: List of contributors.
pyproject.toml: Project metadata. See "Installation" above.
docutils: The project source directory, installed as a Python package.
docs: The project documentation directory. Read docs/index.rst for an overview.
docs/user: The project user documentation directory. Contains the following documents, among others:
- docs/user/tools.rst: Docutils Front-End Tools
- docs/user/latex.rst: Docutils LaTeX Writer
- docs/user/rst/quickstart.rst: A ReStructuredText Primer
- docs/user/rst/quickref.html: Quick reStructuredText (HTML only)