Docutils Distributor’s Guide¶
Author: | Lea Wiemann |
---|---|
Contact: | docutils-develop@lists.sourceforge.net |
Revision: | $Revision: 7463 $ |
Date: | $Date: 2012-06-22 21:49:51 +0200 (Fre, 22. Jun 2012) $ |
Copyright: | This document has been placed in the public domain. |
orphan: | 本文档不能通过导航到达 |
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
.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
anduser/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/
.