Docutils | Overview | About | Users | Reference | Developers

Docutils Distributor's Guide


Lea Wiemann


This document describes how to create packages of Docutils (e.g. for shipping with a Linux distribution). If you have any questions, please direct them to the Docutils-develop mailing list.

First, please download the most current release package and unpack it.


Docutils has the following dependencies:

Python Files

The Docutils Python files must be installed into the site-packages/ directory of Python. Installing with pip should do the trick, but if you want to place the files yourself, you can just install the docutils/ directory of the Docutils tarball to /usr/lib/python/site-packages/docutils/. In this case you should also compile the Python files to .pyc and/or .pyo files so that Docutils doesn't need to be recompiled every time it's executed.


Executable front-end tools are generated and installed in the binary PATH by the installer (pip) from "console_scripts" entry point definitions.

Alternatively, you may install the rst2*.py tools from the tools/ directory of the Docutils source package. On systems that support executable Python scripts, dropping the .py extension is recommended.


The documentation should be generated using To generate HTML for all documentation files, go to the tools/ directory and run:

# Place html4css1.css in base directory.
cp ../docutils/writers/html4css1/html4css1.css ..
./ --stylesheet-path=../html4css1.css ..

Then install the following files to /usr/share/doc/docutils/ (or wherever you install documentation):

Removing the .txt Files

If you are tight with disk space, you can remove all .txt files in the tree except for:

  • those in the licenses/ directory because they have not been processed to HTML and

  • user/rst/cheatsheet.txt and user/rst/demo.txt, which should be readable in source form.

Before you remove the .txt files you should rerun with the --no-source-link switch to avoid broken references to the source files.

Other Files

You may want to install the Emacs-Lisp files tools/editors/emacs/*.el into the appropriate directory.

Configuration File

It is possible to have a system-wide configuration file at /etc/docutils.conf. However, this is usually not necessary. You should not install tools/docutils.conf into /etc/.


While you probably do not need to ship the tests with your distribution, you can test your package by installing it and then running from the tests/ directory of the Docutils tarball.

For more information on testing, view the Docutils Testing page.