Docutils Distributor's Guide

Author: Lea Wiemann
Revision: 7889
Date: 2015-05-08
Copyright: This document has been placed in the public domain.


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 tarball and unpack it.


Docutils has the following dependencies:

Python Files

The Docutils Python files must be installed into the site-packages/ directory of Python. Running python install 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.


The executable front-end tools are located in the tools/ directory of the Docutils tarball.

The rst2*.py tools (except are intended for end-users. You should install them to /usr/bin/. You do not need to change the names (e.g. to because the rst2 prefix is unique.


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.