Author: | Felix Wiemann |
---|---|
Contact: | Felix.Wiemann@ososo.de |
Revision: | 4163 |
Date: | 2005-12-09 |
Copyright: | This document has been placed in the public domain. |
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 has the following dependencies:
Python 2.1 or later is required. While the compiler package from the Tools/ directory of Python's source distribution must be installed for the test suite to pass with Python 2.1, the functionality available to end users should be available without the compiler package as well. So just use ">= Python 2.1" in the dependencies.
Docutils may optionally make use of the PIL (Python Imaging Library). If PIL is present, it is automatically detected by Docutils.
There are three files in the extras/ directory of the Docutils distribution, optparse.py, textwrap.py, and roman.py. For Python 2.1/2.2, all of them must be installed (into the site-packages/ directory). Python 2.3 and later versions have textwrap and optparse included in the standard library, so only roman.py is required here; installing the other files won't hurt, though.
These files are automatically installed by the setup script (when calling "python setup.py install").
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.
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.
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.
If you are tight with disk space, you can remove all .txt files in the tree except for:
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.
You may want to install the Emacs-Lisp files tools/editors/emacs/*.el into the appropriate directory.
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/.
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.