docutils

Docutils -- Python Documentation Utilities

Description

=========================
 README: Docutils 0.22.4
=========================

:Author: David Goodger
:Contact: goodger@python.org
:Date: $Date: 2025-12-18 19:44:54 +0100 (Do, 18. Dez 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.

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.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*:

  1. Open a shell

  2. Go to the directory containing the ``pyproject.toml`` file.

  3. Install the package with **one** of the following commands::

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

     or do a `"manual" install`_.

  4. 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 erro