.. -*- coding: utf-8 -*-

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

:Author: Felix Wiemann
:Contact: Felix.Wiemann@ososo.de
:Revision: $Revision$
:Date: $Date$
: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::

    ./buildhtml.py ..

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.

* ``tools/stylesheets/default.css``, creating the ``tools/`` and
  ``tools/stylesheets/`` directory beforehand.  This file is needed
  for correct viewing of the HTML files.  The remaining contents of
  the ``tools/`` and ``tools/stylesheets/`` directories are not
  needed.

  Be sure not to install ``default.css`` into the root of the
  documentation directory, or the relative references to the
  stylesheet will not work.


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``
as ``./buildhtml.py .. --no-source-link`` to avoid broken references
to the source files.


Other Files
===========

Install ``tools/stylesheets/`` to ``/usr/lib/docutils/stylesheets/``
and ``tools/pep-html-template`` to
``/usr/lib/docutils/pep-html-template``.

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


Configuration File
==================

The system-wide configuration file is located in
``/etc/docutils.conf``.  You should *not* install
``tools/docutils.conf`` into ``/etc/``.  Instead, we recommend that
you create a new ``/etc/docutils.conf`` file containing references to
the appropriate files on your system::

    [html4css1 writer]
    # These entries affect HTML output:
    stylesheet-path: /usr/lib/docutils/stylesheets/default.css

    [pep_html writer]
    # These entries affect reStructuredText-style PEPs:
    template: /usr/lib/docutils/pep-html-template
    stylesheet-path: /usr/lib/docutils/stylesheets/pep.css

(Adjust the paths as necessary.)


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.
