Docutils Distributor’s Guide¶
| Author: | Lea Wiemann |
|---|---|
| Contact: | docutils-develop@lists.sourceforge.net |
| Revision: | $Revision$ |
| Date: | $Date$ |
| Copyright: | This document has been placed in the public domain. |
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.
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.
- There is one file in the
extras/directory of the Docutils distribution,roman.py. It is automatically installed by the setup script (when calling “python setup.py install”).
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
.htmland.txtfiles 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.cssin 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.txtanduser/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/.