docs/dev/distributing.txt

   1 ===============================
   2  Docutils_ Distributor's Guide
   3 ===============================
   4
   5 :Author: Lea Wiemann
   6 :Contact: LeWiemann@gmail.com
   7 :Revision: $Revision$
   8 :Date: $Date$
   9 :Copyright: This document has been placed in the public domain.
  10
  11 .. _Docutils: http://docutils.sourceforge.net/
  12
  13 .. contents::
  14
  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.
  18
  19 First, please download the most current `release tarball`_ and unpack
  20 it.
  21
  22 .. _Docutils-develop: ../user/mailing-lists.html#docutils-develop
  23 .. _release tarball: http://docutils.sourceforge.net/#download
  24
  25
  26 Dependencies
  27 ============
  28
  29 Docutils has the following dependencies:
  30
  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
  36   dependencies.
  37
  38 * Docutils may optionally make use of the PIL (`Python Imaging
  39   Library`_).  If PIL is present, it is automatically detected by
  40   Docutils.
  41
  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
  48   hurt, though.
  49
  50   These files are automatically installed by the setup script (when
  51   calling "python setup.py install").
  52
  53 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
  54
  55
  56 Python Files
  57 ============
  58
  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
  66 time it's executed.
  67
  68
  69 Executables
  70 ===========
  71
  72 The executable front-end tools are located in the ``tools/`` directory
  73 of the Docutils tarball.
  74
  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.
  79
  80
  81 Documentation
  82 =============
  83
  84 The documentation should be generated using ``buildhtml.py``.  To
  85 generate HTML for all documentation files, go to the ``tools/``
  86 directory and run::
  87
  88     # Place html4css1.css in base directory.
  89     cp ../docutils/writers/html4css1/html4css1.css ..
  90     ./buildhtml.py --stylesheet-path=../html4css1.css ..
  91
  92 Then install the following files to ``/usr/share/doc/docutils/`` (or
  93 wherever you install documentation):
  94
  95 * All ``.html`` and ``.txt`` files in the base directory.
  96
  97 * The ``docs/`` directory.
  98
  99   Do not install the contents of the ``docs/`` directory directly to
 100   ``/usr/share/doc/docutils/``; it's incomplete and would contain
 101   invalid references!
 102
 103 * The ``licenses/`` directory.
 104
 105 * ``html4css1.css`` in the base directory.
 106
 107
 108 Removing the ``.txt`` Files
 109 ---------------------------
 110
 111 If you are tight with disk space, you can remove all ``.txt`` files in
 112 the tree except for:
 113
 114 * those in the ``licenses/`` directory because they have not been
 115   processed to HTML and
 116
 117 * ``user/rst/cheatsheet.txt`` and ``user/rst/demo.txt``, which should
 118   be readable in source form.
 119
 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
 122 source files.
 123
 124
 125 Other Files
 126 ===========
 127
 128 You may want to install the Emacs-Lisp files
 129 ``tools/editors/emacs/*.el`` into the appropriate directory.
 130
 131
 132 Configuration File
 133 ==================
 134
 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/``.
 138
 139
 140 Tests
 141 =====
 142
 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
 146 tarball.