Docutils | Overview | About | Users | Reference | Developers

README: Docutils 0.21b.dev

Author:

David Goodger

Contact:
goodger@python.org
Date:
$Date$
Web site:

https://docutils.sourceforge.io/

Copyright:
This document has been placed in the public domain.

Quick-Start

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

  1. Docutils requires Python, available from https://www.python.org/. See Dependencies below for details.

  2. Install the latest stable release from PyPi with pip:

    pip install docutils

    For alternatives and details, see section Installation below.

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

    docutils FAQ.txt FAQ.html

    See Usage below for details.

Purpose

The purpose of the Docutils project is to provide a set of tools for processing plaintext documentation into useful formats, such as HTML, LaTeX, troff (man pages), OpenOffice, and native XML. Support for the following sources has been implemented:

Support for the following sources is planned or provided by third party tools:

Dependencies

To run the code, Python must be installed. (Python is pre-installed with most Linux distributions.)

Recommendations

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

The Docutils Link List records projects that users of Docutils and reStructuredText may find useful.

Installation

The Python Packaging User Guide gives details how to use pip for installing.

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

  • Use su or sudo for a system-wide installation as root, e.g.:

    sudo pip install docutils

Windows

  • The Python FAQ explains how to run a Python program under Windows.

  • Usually, pip is automatically installed if you are using Python downloaded from https://python.org. If not, see the pip documentation.

  • The command window should recognise the word py as an instruction to start the interpreter, e.g.

    py -m pip install docutils

    If this does not work, you may have to specify the full path to the Python executable.

Usage

Start the "docutils" command line application with:

docutils [options] [<source> [<destination>]]

The default action is to convert a reStructuredText document to HTML5, for example:

docutils test.rst test.html

Read the --help option output for details on options and arguments and Docutils Front-End Tools for the full documentation of the various tools.

For programmatic use of the docutils Python package, read the API Reference Material and the source code. Remaining questions may be answered in the Docutils Project Documentation or the Docutils-users mailing list.

Contributions are welcome!

Project Files & Directories

Development version

While we are trying to follow a "release early & often" policy, features are added frequently. We recommend using a current snapshot or a working copy of the repository.

Repository check-out:

To keep up to date on the latest developments, use a working copy of the Docutils version repository.

Snapshots:

To get a repository snapshot, go to https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/ and click the download snapshot button.

Unpack in a temporary directory, not directly in Python's site-packages.

Continue with the Installation instructions below.

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>
py tools\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.

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

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

Ran 1744 tests in 5.859s

OK (skipped=1)
Elapsed time: 6.235 seconds

The number of tests will grow over time, and the times reported will depend on the computer running the tests. Some test are skipped, if optional dependencies (recommendations) are missing. The difference between the two times represents the time required to set up the tests (import modules, create data structures, etc.).

A copy of the test output is written to the file alltests.out.

If any of the tests fail, please open a bug report or send an email (see Bugs). Please include all relevant output, information about your operating system, Python version, and Docutils version. To see the Docutils version, look at the test output or use

docutils --version

Getting Help

All documentation can be reached from the Project Documentation Overview.

The SourceForge project page has links to the tracker, mailing lists, and code repository.

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