docutils

========================= README: Docutils 0.22.1

:Author: David Goodger :Contact: [e-mail] :Date: $Date: 2025-09-17 19:54:28 +0200 (Mi, 17. Sep 2025) $ :Web site: https://docutils.sourceforge.io/ :Copyright: This document has been placed in the public domain.

:Abstract: Docutils is a modular system for processing documentation into useful formats, such as HTML, XML, and LaTeX. For input Docutils supports reStructuredText, an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax.

.. contents::

Quick-Start

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_::

  pip install docutils
  

  For alternatives and details, see section Installation_ below.

• Use the front-end scripts_ to convert reStructuredText documents. Try for example::

  docutils FAQ.rst 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:

• Standalone files.

• PEPs (Python Enhancement Proposals)_.

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

• Inline documentation from Python modules and packages, extracted with namespace context.

• Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).

• Wikis, with global reference lookups of "wiki links".

• Compound documents, such as multiple chapter files merged into a book.

• And others as discovered.

.. _PEPs (Python Enhancement Proposals): https://peps.python.org/pep-0012 .. _third party tools: docs/user/links.html#related-applications

Dependencies

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

• Since version 0.21, Docutils requires Python 3.9 or later.
• Docutils versions 0.19 to 0.20.1 require Python 3.7 or later.
• Docutils versions 0.16 to 0.18 require Python 2.7 or 3.5+.

The type hints added in version 0.22 use Python 3.10 syntax. However, the Python interpreter treats them as annotations unless typing.TYPE_CHECKING is set to True.

.. _Python: https://www.python.org/.

Recommendations

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

• The recommended installer is pip_, setuptools_ works, too.

• The Python Imaging Library_ (PIL) is used for some image manipulation operations.

• The Pygments_ package provides syntax highlight of "code" directives and roles.

• The myst, pycmark, or recommonmark_ parsers can be used to parse input in "Markdown" (CommonMark_) format.

The Docutils Link List <docs/user/links.html>__ records projects that users of Docutils and reStructuredText may find useful.

.. _pip: https://pypi.org/project/pip/ .. _setuptools: https://pypi.org/project/setuptools/ .. _Python Imaging Library: http://www.pythonware.com/products/pil/ .. _Pygments: https://pypi.org/project/Pygments/ .. _myst: https://pypi.org/project/myst-docutils/ .. _pycmark: https://pypi.org/project/pycmark/ .. _recommonmark: https://github.com/rtfd/recommonmark .. _CommonMark: https://spec.commonmark.org/0.30/

Installation

The Python Packaging User Guide_ gives details how to use pip for installing_.

• The simplest way is to install the latest stable release from PyPi::

  pip install docutils
  

• To install a pre-relase, append the option --pre.

• To install a development version_ from source:

  • Open a shell

  • Go to the directory containing the pyproject.toml file.

  • Install the package with one of the following commands::

    pip install -e .  # editable install
    pip install .     # regular install
    

    or do a "manual" install_.

  • Optional steps:

    • Running the test suite_
    • Converting the documentation_

  See also the OS-specific installation instructions below and the Docutils version repository_ documentation.

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

   python3.11 -m pip install docutils
  

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

  To install for different Python versions, repeat step 3 for every required version. The last installed version will be used for the docutils command line application.

.. _Python Packaging User Guide: https://packaging.python.org/en/latest/ .. _use pip for installing: https://packaging.python.org/en/latest/tutorials/installing-packages/ #use-pip-for-installing .. _"editable" install: https://pip.pypa.io/en/stable/topics/local-project-installs/ #editable-installs .. _"manual" install: docs/dev/repository.html#manual-install

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

  __ https://docs.python.org/3/faq/windows.html #how-do-i-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 <https://pip.pypa.io/en/stable/installation/>__.

• 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!

.. _reStructuredText: https://docutils.sourceforge.io/rst.html .. _front-end scripts: .. _Docutils Front-End Tools: docs/user/tools.html .. _API Reference Material: /docs/index.html #api-reference-material-for-client-developers .. _Docutils Project Documentation: /docs/index.html

Project Files & Directories

• README.rst: You're reading it.

• COPYING.rst: Public Domain Dedication and copyright details for non-public-domain files (most are PD).

• FAQ.rst: Frequently Asked Questions (with answers!).

• RELEASE-NOTES.rst: Summary of the major changes in recent releases.

• HISTORY.rst: A detailed change log, for the current and all previous project releases.

• BUGS.rst: Known bugs, and how to report a bug.

• THANKS.rst: List of contributors.

• pyproject.toml: Project metadata. See "Installation" above.

• docutils: The project source directory, installed as a Python package.

• docs: The project documentation directory. Read docs/index.rst for an overview.

• docs/user: The project user documentation directory. Contains the following documents, among others:

  • docs/user/tools.rst: Docutils Front-End Tools
  • docs/user/latex.rst: Docutils LaTeX Writer
  • docs/user/rst/quickstart.rst: A ReStructuredText Primer
  • docs/user/rst/quickref.html: Quick reStructuredText (HTML only)

• docs/ref: The project reference directory. docs/ref/rst/restructuredtext.rst is the reStructuredText reference.

• licenses: Directory containing copies of license files for non-public-domain files.

• tools: Directory for Docutils front-end tools. See docs/user/tools.rst for documentation.

• test: Unit tests. Not required to use the software, but very useful if you're planning to modify it. See Running the Test Suite_ below.

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.

See the Installation_ instructions above.

__ docs/dev/repository.html#checking-out-the-repository .. _Docutils version repository: docs/dev/repository.html .. _sandbox: https://docutils.sourceforge.io/sandbox/README.html

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

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 <BUGS.html>_). 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

.. _Docutils Testing: https://docutils.sourceforge.io/docs/dev/testing.html .. _open a bug report: https://sourceforge.net/p/docutils/bugs/ .. _send an email: mailto:[e-mail] ?subject=Test%20suite%20failure .. _web interface: https://sourceforge.net/p/docutils/mailman/

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.

.. _Project Documentation Overview: docs/index.html .. _project page: https://sourceforge.net/p/docutils .. _Docutils-users: docs/user/mailing-lists.html#docutils-users

.. Emacs settings

Local Variables: mode: indented-text mode: rst indent-tabs-mode: nil sentence-end-double-space: t fill-column: 70 End: