# Docutils Distributor's Guide

Author: | Lea Wiemann
Contact: | docutils-develop@lists.sourceforge.net
Revision: | 7463
Date: | 2012-06-22
Copyright: | This document has been placed in the public domain.

Contents

- Dependencies
- Python Files
- Executables
- Documentation
  - Removing the `.txt` Files
- Other Files
- Configuration File
- Tests

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.

# Dependencies

Docutils has the following dependencies:

- Python 2.4 or later is required. Use ">= Python 2.4" in the dependencies.
- Docutils may optionally make use of the PIL (Python Imaging Library). If PIL is present, it is automatically detected by Docutils.
- There is one file in the `extras/` directory of the Docutils distribution, `roman.py`. It is automatically installed by the setup script (when calling "python setup.py install").

# Python Files

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

# Executables

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

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

# Documentation

The documentation should be generated using `buildhtml.py`. 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 ..
    ./buildhtml.py --stylesheet-path=../html4css1.css ..

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

- All `.html` and `.txt` files in the base directory.

- The `docs/` directory.

  Do not install the contents of the `docs/` directory directly to `/usr/share/doc/docutils/`; it's incomplete and would contain invalid references!

- The `licenses/` directory.

- `html4css1.css` in the base directory.

## 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 `buildhtml.py` 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/`.

# Tests

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