1
===============================
2
Docutils_ Distributor's Guide
3
===============================
6
:Contact: Felix.Wiemann@ososo.de
7
:Revision: $Revision: 4163 $
8
:Date: $Date: 2005-12-09 05:21:34 +0100 (Fri, 09 Dec 2005) $
9
:Copyright: This document has been placed in the public domain.
11
.. _Docutils: http://docutils.sourceforge.net/
15
This document describes how to create packages of Docutils (e.g. for
16
shipping with a Linux distribution). If you have any questions,
17
please direct them to the Docutils-develop_ mailing list.
19
First, please download the most current `release tarball`_ and unpack
22
.. _Docutils-develop: ../user/mailing-lists.html#docutils-develop
23
.. _release tarball: http://docutils.sourceforge.net/#download
29
Docutils has the following dependencies:
31
* Python 2.1 or later is required. While the compiler package from
32
the Tools/ directory of Python's source distribution must be
33
installed for the test suite to pass with Python 2.1, the
34
functionality available to end users should be available without the
35
compiler package as well. So just use ">= Python 2.1" in the
38
* Docutils may optionally make use of the PIL (`Python Imaging
39
Library`_). If PIL is present, it is automatically detected by
42
* There are three files in the ``extras/`` directory of the Docutils
43
distribution, ``optparse.py``, ``textwrap.py``, and ``roman.py``.
44
For Python 2.1/2.2, all of them must be installed (into the
45
``site-packages/`` directory). Python 2.3 and later versions have
46
``textwrap`` and ``optparse`` included in the standard library, so
47
only ``roman.py`` is required here; installing the other files won't
50
These files are automatically installed by the setup script (when
51
calling "python setup.py install").
53
.. _Python Imaging Library: http://www.pythonware.com/products/pil/
59
The Docutils Python files must be installed into the
60
``site-packages/`` directory of Python. Running ``python setup.py
61
install`` should do the trick, but if you want to place the files
62
yourself, you can just install the ``docutils/`` directory of the
63
Docutils tarball to ``/usr/lib/python/site-packages/docutils/``. In
64
this case you should also compile the Python files to ``.pyc`` and/or
65
``.pyo`` files so that Docutils doesn't need to be recompiled every
72
The executable front-end tools are located in the ``tools/`` directory
73
of the Docutils tarball.
75
The ``rst2*.py`` tools (except ``rst2newlatex.py``) are intended for
76
end-users. You should install them to ``/usr/bin/``. You do not need
77
to change the names (e.g. to ``docutils-rst2html.py``) because the
78
``rst2`` prefix is unique.
84
The documentation should be generated using ``buildhtml.py``. To
85
generate HTML for all documentation files, go to the ``tools/``
88
# Place html4css1.css in base directory.
89
cp ../docutils/writers/html4css1/html4css1.css ..
90
./buildhtml.py --stylesheet-path=../html4css1.css ..
92
Then install the following files to ``/usr/share/doc/docutils/`` (or
93
wherever you install documentation):
95
* All ``.html`` and ``.txt`` files in the base directory.
97
* The ``docs/`` directory.
99
Do not install the contents of the ``docs/`` directory directly to
100
``/usr/share/doc/docutils/``; it's incomplete and would contain
103
* The ``licenses/`` directory.
105
* ``html4css1.css`` in the base directory.
108
Removing the ``.txt`` Files
109
---------------------------
111
If you are tight with disk space, you can remove all ``.txt`` files in
114
* those in the ``licenses/`` directory because they have not been
115
processed to HTML and
117
* ``user/rst/cheatsheet.txt`` and ``user/rst/demo.txt``, which should
118
be readable in source form.
120
Before you remove the ``.txt`` files you should rerun ``buildhtml.py``
121
with the ``--no-source-link`` switch to avoid broken references to the
128
You may want to install the Emacs-Lisp files
129
``tools/editors/emacs/*.el`` into the appropriate directory.
135
It is possible to have a system-wide configuration file at
136
``/etc/docutils.conf``. However, this is usually not necessary. You
137
should *not* install ``tools/docutils.conf`` into ``/etc/``.
143
While you probably do not need to ship the tests with your
144
distribution, you can test your package by installing it and then
145
running ``alltests.py`` from the ``tests/`` directory of the Docutils
added
removed
docs/dev/distributing.txt
