|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.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”).
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:
- 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.
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/.