README: Docutils 0.12

Author: David Goodger
Contact: goodger@python.org
Date: 2013-07-22
Web site:http://docutils.sourceforge.net/
Copyright: This document has been placed in the public domain.

Contents

Quick-Start on Debian systems

The reStructuredText tools are installed in the normal system path by the Debian python-docutils package. To convert reStructuredText to another format, use a shell command like:

rst2html /usr/share/doc/python-docutils/FAQ.txt ./FAQ.html

See Usage below for details.

Quick-Start on other systems

This is for those who want to get up & running quickly.

  1. Docutils requires Python (version 2.4 or later), available from

    http://www.python.org/

    See Requirements below for details.

  2. Use the latest Docutils code. Get the code from the Subversion repository or from the snapshot:

    http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar

    See Releases & Snapshots below for details.

  3. Unpack the tarball in a temporary directory (not directly in Python's site-packages), go to the directory created by expanding the archive, and run setup.py install with admin rights. On Windows systems it may be sufficient to double-click install.py.

    See Installation below for details.

  4. Use the front-end scripts to convert reStructuredText documents. Try for example:

    rst2html.py FAQ.txt FAQ.html         (Unix)
    python tools/rst2html.py FAQ.txt FAQ.html  (Windows)
    

    See Usage below for details.

Purpose

The purpose of the Docutils project is to create a set of tools for processing plaintext documentation into useful formats, such as HTML, XML, and LaTeX. Support for the following sources has been implemented:

Support for the following sources is planned:

Releases & Snapshots

While we are trying to follow a "release early & often" policy, features are added very frequently. Since the code in the Subversion repository is usually in a bug-free state, we recommend that you use the current snapshot (which is usually updated within an hour of changes being committed to the repository):

To keep up to date on the latest developments, download fresh copies of the snapshots regularly or use a working copy of the Subversion repository.

Requirements

To run the code, Python must be installed. Docutils is compatible with Python versions from 2.4 up to 2.7 and versions 3.1 and 3.2 (cf. Python 3 compatibility).

Docutils uses the following packages for enhanced functionality, if they are installed:

Python 3 compatibility

The Docutils codebase is written for Python 2 and uses "on-demand" translation for porting to Python 3.

  • The setup.py script generates Python 3 compatible sources in build/ and tests in tests3/ sub-directories during installation with Python 3.
  • The scripts in the tools/ sub-directory work with all supported Python versions without conversion.
  • To convert the sources without installing (e.g. for testing), run python3 setup.py build.
  • When editing the source, do changes on the Python 2 versions of the files and re-run the build command.

Using Docutils with Python 3.x is less tested and might still have some issues.

Project Files & Directories

Generated directories when installing under Python 3:

Installation

The first step is to expand the .tgz archive in a temporary directory (not directly in Python's site-packages). It contains a distutils setup file "setup.py". OS-specific installation instructions follow.

GNU/Linux, BSDs, Unix, Mac OS X, etc.

  1. Open a shell.

  2. Go to the directory created by expanding the archive:

    cd <archive_directory_path>
    
  3. Install the package (you may need root permissions to complete this step):

    su
    (enter admin password)
    python setup.py install
    

    If the python executable isn't on your path, you'll have to specify the complete path, such as /usr/local/bin/python.

    To install for a specific Python version, use this version in the setup call, e.g.

    python3.1 setup.py install
    

    To install for different Python versions, repeat step 3 for every required version. The last installed version will be used in the shebang line of the rst2*.py wrapper scripts.

Windows

Just double-click install.py. If this doesn't work, try the following:

  1. Open a DOS Box (Command Shell, MS-DOS Prompt, or whatever they're calling it these days).

  2. Go to the directory created by expanding the archive:

    cd <archive_directory_path>
    
  3. Install the package:

    <path_to_python.exe>\python setup.py install
    

    To install for a specific python version, specify the Python executable for this version.

    To install for different Python versions, repeat step 3 for every required version.

Optional steps:

Usage

There are many front-end tools in the unpacked "tools" subdirectory. Installation under Unix places copies in the PATH. You may want to begin with the "rst2html.py" front-end tool. Most tools take up to two arguments, the source path and destination path, with STDIN and STDOUT being the defaults. Use the "--help" option to the front-end tools for details on options and arguments. See Docutils Front-End Tools (docs/user/tools.txt) for full documentation.

On a Debian system the included tools (with the exception of quicktest.py and the development tools in the dev/ directory) are installed into the normal system path, so you can run rst2html.py with a command like:

rst2html example.txt example.html

The package modules are continually growing and evolving. The docutils.statemachine module is usable independently. It contains extensive inline documentation (in reStructuredText format of course).

Contributions are welcome!

Converting the documentation

After unpacking and installing the Docutils package, the following shell commands will generate HTML for all included documentation:

cd <archive_directory_path>/tools
./buildhtml.py ../

On Windows systems, type:

cd <archive_directory_path>\tools
python buildhtml.py ..

The final directory name of the <archive_directory_path> is "docutils" for snapshots. For official releases, the directory may be called "docutils-X.Y.Z", where "X.Y.Z" is the release version. Alternatively:

cd <archive_directory_path>
tools/buildhtml.py --config=tools/docutils.conf          (Unix)
python tools\buildhtml.py --config=tools\docutils.conf   (Windows)

Some files may generate system messages (warnings and errors). The docs/user/rst/demo.txt file (under the archive directory) contains five intentional errors. (They test the error reporting mechanism!)

Running the Test Suite

The test suite is documented in Docutils Testing (docs/dev/testing.txt).

To run the entire test suite, open a shell and use the following commands:

cd <archive_directory_path>/test
./alltests.py

Under Windows, type:

cd <archive_directory_path>\test
python alltests.py

For testing with Python 3 use the converted test suite:

cd <archive_directory_path>/test3
python3 alltests.py

You should see a long line of periods, one for each test, and then a summary like this:

Ran 1111 tests in 24.653s

OK
Elapsed time: 26.189 seconds

The number of tests will grow over time, and the times reported will depend on the computer running the tests. The difference between the two times represents the time required to set up the tests (import modules, create data structures, etc.).

If any of the tests fail, please open a bug report, send email, or post a message via the web interface (see Bugs). Please include all relevant output, information about your operating system, Python version, and Docutils version. To see the Docutils version, use one of the rst2* front ends or tools/quicktest.py with the --version option, e.g.:

cd ../tools
./quicktest.py --version

Windows users type these commands:

cd ..\tools
python quicktest.py --version

Getting Help

If you have questions or need assistance with Docutils or reStructuredText, please post a message to the Docutils-users mailing list.