1 ===============================
2 Docutils_ Distributor's Guide
3 ===============================
6 :Contact: docutils-develop@lists.sourceforge.net
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.4 or later is required. Use ">= Python 2.4" in the
34 * Docutils may optionally make use of the PIL (`Python Imaging
35 Library`_). If PIL is present, it is automatically detected by
38 * Docutils recommends the `Pygments`_ syntax hightlighter. If available, it
39 is used for highlighting the content of `code directives`_ and roles as
40 well as included source code files (with the "code" option to the include_
43 * There is one file in the ``extras/`` directory of the Docutils
44 distribution, ``roman.py``. It is automatically installed by the setup
45 script (when calling "python setup.py install").
47 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
48 .. _Pygments: http://pygments.org/
49 .. _code directives: ../ref/rst/directives.html#code
50 .. _include: ../ref/rst/directives.html#include
56 The Docutils Python files must be installed into the
57 ``site-packages/`` directory of Python. Running ``python setup.py
58 install`` should do the trick, but if you want to place the files
59 yourself, you can just install the ``docutils/`` directory of the
60 Docutils tarball to ``/usr/lib/python/site-packages/docutils/``. In
61 this case you should also compile the Python files to ``.pyc`` and/or
62 ``.pyo`` files so that Docutils doesn't need to be recompiled every
69 The executable front-end tools are located in the ``tools/`` directory
70 of the Docutils tarball.
72 The ``rst2*.py`` tools (except ``rst2newlatex.py``) are intended for
73 end-users. You should install them to ``/usr/bin/``. You do not need
74 to change the names (e.g. to ``docutils-rst2html.py``) because the
75 ``rst2`` prefix is unique.
81 The documentation should be generated using ``buildhtml.py``. To
82 generate HTML for all documentation files, go to the ``tools/``
85 # point to the stylesheet and template for the site
86 ./buildhtml.py --stylesheet-path=../docs/_template/web.css,../docutils/writers/html_base/html-base.css --template=../docs/_template/template.html ..
88 Then install the following files to ``/usr/share/doc/docutils/`` (or
89 wherever you install documentation):
91 * All ``.html`` and ``.txt`` files in the base directory.
93 * The ``docs/`` directory.
95 Do not install the contents of the ``docs/`` directory directly to
96 ``/usr/share/doc/docutils/``; it's incomplete and would contain
99 * The ``licenses/`` directory.
101 * ``html4css1.css`` in the base directory.
104 Removing the ``.txt`` Files
105 ---------------------------
107 If you are tight with disk space, you can remove all ``.txt`` files in
110 * those in the ``licenses/`` directory because they have not been
111 processed to HTML and
113 * ``user/rst/cheatsheet.txt`` and ``user/rst/demo.txt``, which should
114 be readable in source form.
116 Before you remove the ``.txt`` files you should rerun ``buildhtml.py``
117 with the ``--no-source-link`` switch to avoid broken references to the
124 You may want to install the Emacs-Lisp files
125 ``tools/editors/emacs/*.el`` into the appropriate directory.
131 It is possible to have a system-wide configuration file at
132 ``/etc/docutils.conf``. However, this is usually not necessary. You
133 should *not* install ``tools/docutils.conf`` into ``/etc/``.
139 While you probably do not need to ship the tests with your
140 distribution, you can test your package by installing it and then
141 running ``alltests.py`` from the ``tests/`` directory of the Docutils