Docutils Distributor's Guide

Author:	Lea Wiemann
Contact:	docutils-develop@lists.sourceforge.net
Revision:	9051
Date:	2022-04-02
Copyright:	This document has been placed in the public domain.

Contents

Dependencies
Python Files
Executables
Documentation
- Removing the .txt Files
Other Files
Configuration File
Tests

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 3.7 or later is required. Use ">= Python 3.7" in the dependencies.
Docutils may optionally make use of the PIL (Python Imaging Library or Pillow). 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).
Docutils can use the recommonmark parser to parse input in the Markdown format (new in 0.17).

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 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.