===============================
 Docutils_ Distributor's Guide
===============================

:Author: Felix Wiemann
:Contact: Felix.Wiemann@ososo.de
:Revision: $Revision: 4163 $
:Date: $Date: 2005-12-09 05:21:34 +0100 (Fri, 09 Dec 2005) $
:Copyright: This document has been placed in the public domain.

.. _Docutils: http://docutils.sourceforge.net/

.. contents::

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-develop: ../user/mailing-lists.html#docutils-develop
.. _release tarball: http://docutils.sourceforge.net/#download


Dependencies
============

Docutils has the following dependencies:

* Python 2.1 or later is required.  While the compiler package from
  the Tools/ directory of Python's source distribution must be
  installed for the test suite to pass with Python 2.1, the
  functionality available to end users should be available without the
  compiler package as well.  So just use ">= Python 2.1" 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 are three files in the ``extras/`` directory of the Docutils
  distribution, ``optparse.py``, ``textwrap.py``, and ``roman.py``.
  For Python 2.1/2.2, all of them must be installed (into the
  ``site-packages/`` directory).  Python 2.3 and later versions have
  ``textwrap`` and ``optparse`` included in the standard library, so
  only ``roman.py`` is required here; installing the other files won't
  hurt, though.

  These files are automatically installed by the setup script (when
  calling "python setup.py install").

.. _Python Imaging Library: http://www.pythonware.com/products/pil/


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.