=============================== Docutils_ Distributor's Guide =============================== :Author: Lea Wiemann :Contact: docutils-develop@lists.sourceforge.net :Revision: $Revision: 7889 $ :Date: $Date: 2015-05-08 15:56:32 +0000 (Fri, 08 May 2015) $ :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.4 or later is required. Use ">= Python 2.4" in the dependencies. * Docutils may optionally make use of the PIL (`Python Imaging Library`_). If PIL is present, it is automatically detected by Docutils. * Docutils recommends the `Pygments`_ syntax hightlighter. If available, it is used for highlighting the content of `code directives`_ and roles as well as included source code files (with the "code" option to the include_ directive). .. _Python Imaging Library: http://www.pythonware.com/products/pil/ .. _Pygments: http://pygments.org/ .. _code directives: ../ref/rst/directives.html#code .. _include: ../ref/rst/directives.html#include 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:: # Place html4css1.css in base directory. cp ../docutils/writers/html4css1/html4css1.css .. ./buildhtml.py --stylesheet-path=../html4css1.css .. 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. * ``html4css1.css`` in the base directory. 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`` with the ``--no-source-link`` switch to avoid broken references to the source files. Other Files =========== You may want to install the Emacs-Lisp files ``tools/editors/emacs/*.el`` into the appropriate directory. Configuration File ================== It is possible to have a system-wide configuration file at ``/etc/docutils.conf``. However, this is usually not necessary. You should *not* install ``tools/docutils.conf`` into ``/etc/``. 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. For more information on testing, view the `Docutils Testing`_ page. .. _Docutils Testing: http://docutils.sourceforge.net/docs/dev/testing.html