docs/dev/distributing.txt

   1 ===============================
   2  Docutils_ Distributor's Guide
   3 ===============================
   4
   5 :Author: Lea Wiemann
   6 :Contact: docutils-develop@lists.sourceforge.net
   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.4 or later is required.  Use ">= Python 2.4" in the
  32   dependencies.
  33
  34 * Docutils may optionally make use of the PIL (`Python Imaging
  35   Library`_).  If PIL is present, it is automatically detected by
  36   Docutils.
  37
  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_
  41   directive).
  42
  43 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
  44 .. _Pygments: http://pygments.org/
  45 .. _code directives: ../ref/rst/directives.html#code
  46 .. _include: ../ref/rst/directives.html#include
  47
  48
  49 Python Files
  50 ============
  51
  52 The Docutils Python files must be installed into the
  53 ``site-packages/`` directory of Python.  Running ``python setup.py
  54 install`` should do the trick, but if you want to place the files
  55 yourself, you can just install the ``docutils/`` directory of the
  56 Docutils tarball to ``/usr/lib/python/site-packages/docutils/``.  In
  57 this case you should also compile the Python files to ``.pyc`` and/or
  58 ``.pyo`` files so that Docutils doesn't need to be recompiled every
  59 time it's executed.
  60
  61
  62 Executables
  63 ===========
  64
  65 The executable front-end tools are located in the ``tools/`` directory
  66 of the Docutils tarball.
  67
  68 The ``rst2*.py`` tools (except ``rst2newlatex.py``) are intended for
  69 end-users.  You should install them to ``/usr/bin/``.  You do not need
  70 to change the names (e.g. to ``docutils-rst2html.py``) because the
  71 ``rst2`` prefix is unique.
  72
  73
  74 Documentation
  75 =============
  76
  77 The documentation should be generated using ``buildhtml.py``.  To
  78 generate HTML for all documentation files, go to the ``tools/``
  79 directory and run::
  80
  81     # Place html4css1.css in base directory.
  82     cp ../docutils/writers/html4css1/html4css1.css ..
  83     ./buildhtml.py --stylesheet-path=../html4css1.css ..
  84
  85 Then install the following files to ``/usr/share/doc/docutils/`` (or
  86 wherever you install documentation):
  87
  88 * All ``.html`` and ``.txt`` files in the base directory.
  89
  90 * The ``docs/`` directory.
  91
  92   Do not install the contents of the ``docs/`` directory directly to
  93   ``/usr/share/doc/docutils/``; it's incomplete and would contain
  94   invalid references!
  95
  96 * The ``licenses/`` directory.
  97
  98 * ``html4css1.css`` in the base directory.
  99
 100
 101 Removing the ``.txt`` Files
 102 ---------------------------
 103
 104 If you are tight with disk space, you can remove all ``.txt`` files in
 105 the tree except for:
 106
 107 * those in the ``licenses/`` directory because they have not been
 108   processed to HTML and
 109
 110 * ``user/rst/cheatsheet.txt`` and ``user/rst/demo.txt``, which should
 111   be readable in source form.
 112
 113 Before you remove the ``.txt`` files you should rerun ``buildhtml.py``
 114 with the ``--no-source-link`` switch to avoid broken references to the
 115 source files.
 116
 117
 118 Other Files
 119 ===========
 120
 121 You may want to install the Emacs-Lisp files
 122 ``tools/editors/emacs/*.el`` into the appropriate directory.
 123
 124
 125 Configuration File
 126 ==================
 127
 128 It is possible to have a system-wide configuration file at
 129 ``/etc/docutils.conf``.  However, this is usually not necessary.  You
 130 should *not* install ``tools/docutils.conf`` into ``/etc/``.
 131
 132
 133 Tests
 134 =====
 135
 136 While you probably do not need to ship the tests with your
 137 distribution, you can test your package by installing it and then
 138 running ``alltests.py`` from the ``tests/`` directory of the Docutils
 139 tarball.
 140
 141 For more information on testing, view the `Docutils Testing`_ page.
 142
 143 .. _Docutils Testing: http://docutils.sourceforge.net/docs/dev/testing.html