Index of /sandbox/grubert/test

[ICO]NameLast modifiedSizeDescription

[DIR]Parent Directory  -  
[TXT]docinfo.txt22-Mar-2013 08:16 655  
[TXT]from_test_txt-04.txt22-Mar-2013 08:16 223  
[TXT]from_test_txt-06.txt22-Mar-2013 08:16 151  
[TXT]from_test_txt-10.txt22-Mar-2013 08:16 406  
[TXT]from_test_txt-14.txt22-Mar-2013 08:16 217  
[TXT]from_test_txt-15.txt22-Mar-2013 08:16 1.1K 
[TXT]from_test_txt-17.txt22-Mar-2013 08:16 208  
[TXT]from_test_txt-19.txt22-Mar-2013 08:16 514  
[TXT]characters.txt22-Mar-2013 08:16 2.3K 
[TXT]docinfo-2.txt22-Mar-2013 08:16 740  
[TXT]footnotes.txt22-Mar-2013 08:16 3.9K 
[TXT]from_test_txt-01.txt22-Mar-2013 08:16 1.9K 
[TXT]from_test_txt-02.txt22-Mar-2013 08:16 112  
[TXT]from_test_txt-03.txt22-Mar-2013 08:16 1.6K 
[TXT]from_test_txt-05.txt22-Mar-2013 08:16 258  
[TXT]from_test_txt-07.txt22-Mar-2013 08:16 395  
[TXT]from_test_txt-08.txt22-Mar-2013 08:16 778  
[TXT]from_test_txt-09.txt22-Mar-2013 08:16 400  
[TXT]from_test_txt-11.txt22-Mar-2013 08:16 254  
[TXT]from_test_txt-12.txt22-Mar-2013 08:16 1.2K 
[TXT]from_test_txt-13.txt22-Mar-2013 08:16 803  
[TXT]from_test_txt-16.txt22-Mar-2013 08:16 2.7K 
[TXT]from_test_txt-18.txt22-Mar-2013 08:16 514  
[TXT]images.txt22-Mar-2013 08:16 669  
[TXT]internal_href.txt22-Mar-2013 08:16 127  
[TXT]links.txt22-Mar-2013 08:16 2.0K 
[TXT]literal.txt22-Mar-2013 08:16 2.6K 
[TXT]no-citations.txt22-Mar-2013 08:16 249  
[TXT]tables-multirow.txt22-Mar-2013 08:16 1.1K 
[TXT]tables.txt22-Mar-2013 08:16 8.5K 
[TXT]toc.txt22-Mar-2013 08:16 262  
[   ]characters.txt.tex.ref17-Mar-2015 15:26 4.6K 
[   ]docinfo-2.txt.tex.ref17-Mar-2015 15:26 2.8K 
[   ]docinfo.txt.tex.ref17-Mar-2015 15:26 2.1K 
[   ]footnotes.txt.tex.ref17-Mar-2015 15:26 6.2K 
[   ]from_test_txt-01.txt.tex.ref17-Mar-2015 15:26 4.1K 
[   ]from_test_txt-02.txt.tex.ref17-Mar-2015 15:26 1.3K 
[   ]from_test_txt-03.txt.tex.ref17-Mar-2015 15:26 7.1K 
[   ]from_test_txt-04.txt.tex.ref17-Mar-2015 15:26 1.2K 
[   ]from_test_txt-05.txt.tex.ref17-Mar-2015 15:26 2.2K 
[   ]from_test_txt-06.txt.tex.ref17-Mar-2015 15:26 1.1K 
[   ]from_test_txt-07.txt.tex.ref17-Mar-2015 15:26 1.6K 
[   ]from_test_txt-08.txt.tex.ref17-Mar-2015 15:26 2.4K 
[   ]from_test_txt-09.txt.tex.ref17-Mar-2015 15:26 1.4K 
[   ]from_test_txt-10.txt.tex.ref17-Mar-2015 15:26 1.3K 
[   ]from_test_txt-11.txt.tex.ref17-Mar-2015 15:26 1.2K 
[   ]from_test_txt-12.txt.tex.ref17-Mar-2015 15:26 0  
[   ]from_test_txt-13.txt.tex.ref17-Mar-2015 15:26 3.4K 
[   ]from_test_txt-14.txt.tex.ref17-Mar-2015 15:26 2.2K 
[   ]from_test_txt-15.txt.tex.ref17-Mar-2015 15:26 4.6K 
[   ]from_test_txt-16.txt.tex.ref17-Mar-2015 15:26 7.4K 
[   ]from_test_txt-17.txt.tex.ref17-Mar-2015 15:26 1.1K 
[   ]from_test_txt-18.txt.tex.ref17-Mar-2015 15:26 1.4K 
[   ]from_test_txt-19.txt.tex.ref17-Mar-2015 15:26 1.4K 
[TXT]header.txt17-Mar-2015 15:26 47  
[   ]header.txt-embed-stylesheet-sty.tex.ref17-Mar-2015 15:26 907  
[TXT]header.txt-embed-stylesheet.err.ref17-Mar-2015 15:26 907  
[   ]header.txt-embed-stylesheet.tex.ref17-Mar-2015 15:26 880  
[   ]header.txt.tex.ref17-Mar-2015 15:26 796  
[   ]images.txt.tex.ref17-Mar-2015 15:26 3.1K 
[   ]internal_href.txt.tex.ref17-Mar-2015 15:26 936  
[   ]links.txt.tex.ref17-Mar-2015 15:26 3.9K 
[   ]literal.txt.tex.ref17-Mar-2015 15:26 4.1K 
[   ]no-citations.txt.tex.ref17-Mar-2015 15:26 1.5K 
[   ]tables-multirow.txt.tex.ref17-Mar-2015 15:26 2.7K 
[   ]tables.txt.tex.ref17-Mar-2015 15:26 8.0K 
[   ]toc.txt.tex.ref17-Mar-2015 15:26 1.3K 

README: Docutils

README: Docutils

Author: David Goodger
Date: 2003-08-16
Web site:
Copyright: This document has been placed in the public domain.


Thank you for downloading the Python Docutils project archive. As this is a work in progress, please check the project website for updated working files (snapshots). This project should be considered highly experimental; APIs are subject to change at any time.


This is for those who want to get up & running quickly. Read on for complete details.

  1. Get and install the latest release of Python, available from

    Python 2.2 or later [1] is required; Python 2.2.2 or later is recommended.

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

    See Releases & Snapshots below for details.

  3. Unpack the tarball in a temporary directory (not directly in Python's site-packages) and install with the standard

    python install

    See Installation below for details.

  4. Use a front-end tool from the "tools" subdirectory of the same directory as in step 3. For example:

    cd tools test.txt test.html

    See Usage below for details.


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 TeX. Support for the following sources has been implemented:

Support for the following sources is planned:

Releases & Snapshots

Putting together an official "Release" of Docutils is a significant effort, so it isn't done that often. In the meantime, the CVS snapshots always contain the latest code and documentation, usually updated within an hour of changes being committed to the repository, and usually bug-free:

To keep up to date on the latest developments, download fresh copies of the snapshots regularly. New functionality is being added weekly, sometimes daily. (There's also the CVS repository, and a mailing list for CVS messages. See the web site [address above] or spec/notes.txt for details.)


To run the code, Python 2.2 or later [1] must already be installed. The latest release is recommended (2.2.2 as of this writing). Python is available from

[1](1, 2) Python 2.1 may be used providing the compiler package is installed. The compiler package can be found in the Tools/ directory of Python 2.1's source distribution.

Project Files & Directories


The first step is to expand the .tar.gz or .tgz archive in a temporary directory (not directly in Python's site-packages). It contains a distutils setup file "". 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:

    python install

    If the python executable isn't on your path, you'll have to specify the complete path, such as /usr/local/bin/python. You may need root permissions to complete this step.

You can also just run; it does the same thing.


  1. Open a DOS box (Command Shell, MSDOS 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 install

If your system is set up to run Python when you double-click on .py files, you can run to do the same as the above.

Mac OS 8/9

  1. Open the folder containing the expanded archive.

  2. Double-click on the file "", which should be a "Python module" file.

    If the file isn't a "Python module", the line endings are probably also wrong, and you will need to set up your system to recognize ".py" file extensions as Python files. See for detailed instructions. Once set up, it's easiest to start over by expanding the archive again.

  3. The distutils options window will appear. From the "Command" popup list choose "install", click "Add", then click "OK".

If is a "Python module" (see step 2 above if it isn't), you can run it (double-click) instead of the above. The distutils options window will not appear.


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

cd <archive_directory_path>/tools ../

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

cd <archive_directory_path>
tools/ --config=tools/docutils.conf

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

There are many front-end tools in the unpacked "tools" subdirectory. You may want to begin with the "" 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/tools.txt) for full documentation.

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!

Running the Test Suite

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

cd <archive_directory_path>/test

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

Ran 518 tests in 24.653s

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 or send email. Please include all relevant output, information about your operating system, Python version, and Docutils version. To see the Docutils version, use these commands:

cd ../tools
./ --version

Getting Help

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