Infrastructure as Code

Repositories with services as code

Repositories Projects
1
 Packages

docutils (0.22.4)

Published 2026-05-18 23:52:27 +03:00 by mpavlov

Installation

pip install --index-url  docutils

About this package

Docutils -- Python Documentation Utilities

========================= 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 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:docutils-users@lists.sourceforge.net ?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:

Requirements

Requires Python: >=3.9
Details
PyPI
2026-05-18 23:52:27 +03:00
1
Project Site
618 KiB
Assets (1)
docutils-0.22.4-py3-none-any.whl 618 KiB
Versions (1) View all
0.22.4 2026-05-18