| Author: | David Goodger |
|---|---|
| Contact: | goodger@python.org |
| Date: | 2022-07-05 |
| Web site: | https://docutils.sourceforge.io/ |
| Copyright: | This document has been placed in the public domain. |
Contents
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/python3-docutils/FAQ.txt ./FAQ.html
See Usage below for details.
This is for those who want to get up & running quickly.
Docutils requires Python, available from https://www.python.org/. See Dependencies below for details.
Install the latest stable release from PyPi with pip:
python3 -m pip install docutils
For alternatives and details, see section Installation below.
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.
The purpose of the Docutils project is to create 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:
To run the code, Python must be installed. (Python is pre-installed with most Linux distributions.)
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.
While we are trying to follow a "release early & often" policy, features are added frequently. Since the code in the Docutils version repository is usually in a bug-free state, we recommend using a current snapshot or a working copy.
Continue with the Installation instructions below.
The simplest way is to install the latest stable release from PyPi with pip:
python3 -m pip install docutils
To install a pre-relase, append the option --pre.
To install a development version from source with setuptools:
Go to the directory containing the file setup.py.
A snapshot must be unpacked in a temporary directory (not directly in Python's site-packages) first.
Run setup.py install. See also OS-specific installation instructions below.
For installing "by hand" or in "development mode", see the editable installs section in the Docutils version repository documentation.
Optional steps:
Open a shell.
Go to the directory containing setup.py:
cd <archive_directory_path>
Install the package (you may need root permissions to complete this step):
su (enter admin password) python3 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.7 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 front-end scripts.
Just double-click install.py. If this doesn't work, try the following:
Open a DOS Box (Command Shell, MS-DOS Prompt, or whatever they're calling it these days).
Go to the directory created by expanding the archive:
cd <archive_directory_path>
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.
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 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!
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!)
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 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.).
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 one of the front-end scripts with the --version option.
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.