docutils-0.22.2 (Python module) (Wait until sphinx can use this version)

[Bruce Dubbs]

New minor version.

[Bruce Dubbs]

Release 0.22 (2026-07-29)

• No changes to rc5.

Release 0.22rc5 (2025-06-24)

• Targets generated from hyperlink references with embedded URI or alias are no longer "explicit" but "implicit" (i.e. with the same priority as auto-generated section targets, see implicit hyperlink targets).
• Don't report an error for duplicate targets with identical refname.

Release 0.22rc4 (2025-06-17)

• Drop the "name" option of the "target-notes" directive. (Report an error instead of silently ignoring the value.)
• New alias "rst-class" for the "class"_ directive to improve the compatibility with Sphinx.

Release 0.22rc3 (2025-06-10)

• New objects -transforms.references.CitationReferences
  • Mark citation_references as resolved if the backend uses a BibTeX database.
• Output changes
  • manpage: Do not drop text of internal targets.

Release 0.22rc2 (2025-05-22)

• Fix backwards-compatibility problem:

    reStructuredText section parsing no longer requires
    `parsers.rst.states.RSTStateMachine.memo.section_parents`
    (a cache introduced in Docutils 0.22rc1).
  

• Deprecate parsers.rst.states.Struct (obsoleted by types.SimpleNamespace).

Release 0.22rc1 (2025-05-06)

reStructuredText:
  - Support `CSS3 units`_. This adds "ch", "rem", "vw", "vh", "vmin",
    "vmax", and "Q" to the `supported length units`__. Note that some
    output formats don't support all units.
  - New option "figname" for the `"figure"`_ directive.

  .. _CSS3 units: https://www.w3.org/TR/css-values-3/#lengths
  __ docs/ref/rst/restructuredtext.html#length-units

Document Tree / Docutils DTD
  - Allow multiple <term> elements in a `\<definition_list_item>`__
    (third-party writers may need adaption).
  - The first element in a <figure> may also be a <reference>
    (with nested "clickable" <image>).

  __ docs/ref/doctree.html#definition-list-item

Configuration changes
  - Make MathML the default math_output_ for the "html5" writer.
  - Change the default input_encoding_ from ``None`` (auto-detect) to "utf-8".
  - Drop short options ``-i`` and ``-o``.
    Use the long equivalents ``--input-encoding`` and ``--output-encoding``.
    (See `command line interface`_ for the rationale.)
  - Rename configuration setting "output" to "output_path_".
  - New setting "validate_".
  - The manpage writer now recognizes the sections [writers] and
    [manpage writer] with the new setting `text_references`_.

Output changes
  LaTeX:
     Don't wrap references with custom reference_label_ in a ``\hyperref``
     command. The "hyperref" package generates hyperlinks for labels by
     default, so there is no change in the PDF
     (except for the starred forms like ``reference_label = \ref*``).

     Stop requiring "ifthen.sty". Add "ifthen" to the stylesheet__ setting
     or replace use of ``\ifthenelse{\isundefined...`` with the eTeX
     primitive ``\ifdefined``.

     __ docs/user/config.html#stylesheet-2

  HTML5:
     Unitless image_ size measures__ are written as <img> "width" and
     "hight" values instead of "style" rules.  The current behaviour
     is kept for values with units, so users may specify, e.g. ``:width:
     50px`` instead of ``:width: 50`` to override CSS stylesheet rules.
     __ docs/ref/doctree.html#measure

  manpage:
     Don't UPPERCASE section headings.

     Handle hyperlink references (see the text_references_ setting).

  null:
     The "null" writer output changed from None to the empty string.

     `publish_string()` now returns a `bytes` or `str` instance
     for all writers (as documented).

New objects
  `parsers.docutils_xml`
     parser for `Docutils XML`_ (e.g., the output of the "xml" writer).
     Provisional.

     Try ``docutils --parser=xml test/data/multiple-term-definitions.xml``
     or use the :parser: option of the `"include"`_ directive to include
     an XML file in a rST document.

  `nodes.Element.validate()`
     Raise `nodes.ValidationError` if the element does not comply with
     the `Docutils Document Model`_.
     Provisional.

  `writers.DoctreeTranslator`
     Generic Docutils document tree translator base class with
     `uri2path()` auxiliary method.
     Provisional.

Removed objects
  `core.Publisher.setup_option_parser()`
     internal, obsolete,
  `frontend.ConfigParser.get_section()`
     obsoleted by the configparser's "Mapping Protocol Access",
  `frontend.OptionParser.set_defaults_from_dict()`
     obsolete,
  `nodes.Element.set_class()`
     obsolete, append to Element['classes'] directly,
  `parsers.rst.directives.tables.CSVTable.decode_from_csv()`
     not required with Python 3,
  `parsers.rst.directives.tables.CSVTable.encode_from_csv()`
     not required with Python 3,
  `transforms.writer_aux.Compound`
     not used since Dec 2010,
  `utils.error_reporting` 
     obsolete in Python 3,
  `utils.Reporter.set_conditions()`
     obsolete, set attributes via configuration settings or directly.
     
Removed localisations
  Mistranslations of the "admonition" directive name:
     Use "advies" (af), "varsel" (da), "warnhinweis" (de), "aviso" (es),
     "sciigo" (eo), "annonce" (fr), "avviso" (it), "advies" (nl),
     "zauważenie" (pl) (introduced in Docutils 0.21)
     or the English name "admonition".

New files
  ``docutils/parsers/rst/include/html-roles.txt``
     `Standard definition file`_ for additional roles matching HTML tags.

Removed files
  ``tools/rst2odt_prepstyles.py``
     Obsoleted by `writers.odf_odt.prepstyles`.
  ``docutils/utils/roman.py``
     Obsoleted by ``docutils/utils/_roman_numerals.py``

• Bugfixes and improvements

[Bruce Dubbs]

When trying to install this package I got:

ERROR: pip's dependency resolver does not currently take into 
account all the packages that are installed. This behaviour is 
the source of the following dependency conflicts.

sphinx-rtd-theme 3.0.2 requires docutils<0.22,>0.18, but you have 
docutils 0.22 which is incompatible.

sphinx 8.2.3 requires docutils<0.22,>=0.20, but you 
have docutils 0.22 which is incompatible.

Wait for sphinx to be updated.

[Joe Locash]

Replying to Bruce Dubbs:

Wait for sphinx to be updated.

​https://github.com/sphinx-doc/sphinx/commit/5d3bb2e3b7c47e4ecd540c657018f16b961c821b

sed -i 's/0\.22/0\.23/' pyproject.toml

should do it

[Joe Locash]

extra-cmake-modules also needs a change:

​https://github.com/KDE/extra-cmake-modules/commit/888ee3e04e73ce93a83df4804856190fb35ff8d6

It applies cleanly to 6.13.0.

[Bruce Dubbs]

Replying to Joe Locash:

extra-cmake-modules also needs a change:

​https://github.com/KDE/extra-cmake-modules/commit/888ee3e04e73ce93a83df4804856190fb35ff8d6

It applies cleanly to 6.13.0.

extra-cmake-modules is a part of kf6. Version 6.17.0 is scheduled for release on Aug 8th. We will wait to see if a change is needed then.

[Joe Locash]

Replying to Bruce Dubbs:

Replying to Joe Locash:

extra-cmake-modules also needs a change:

​https://github.com/KDE/extra-cmake-modules/commit/888ee3e04e73ce93a83df4804856190fb35ff8d6

It applies cleanly to 6.13.0.

extra-cmake-modules is a part of kf6. Version 6.17.0 is scheduled for release on Aug 8th. We will wait to see if a change is needed then.

The change is needed for 6.17.0.

[pierre]

I think we should add the sed in sphinx and a similar one in sphinx_rtd_theme. I've done that kind of version relaxing in the past without problem. The patch for ECM is already in the book. Then we could update to 0.22.2.

[pierre]

Release 0.22.2 (2025-09-20)

Remove a spurious vim .swp-file to fix bug #513.

Release 0.22.1 (2025-09-17)

docutils/frontend.py, docutils/writers/

More consistent and concise command line help.

docutils/nodes.py

nodes.Element.section_hierarchy() now returns only elements with non-empty "parent" attribute.

docutils/parsers/rst/states.py

Relax "section title" system messages from SEVERE to ERROR.

Fix behaviour with nested parsing into a detached node (cf. bugs #508 and #509).

New attribute NestedStateMachine.parent_state_machine. Use case: update the "current node" of parent state machine(s) after nested parsing.

Better error messages for grid table markup errors (bug #504), based on patch #214 by Jynn Nelson.

docutils/transforms/references.py

Better error reports for hyperlinks with embedded URI or alias.

docutils/writers/latex2e/init.py

Add cross-reference anchors (\phantomsection\label{...}) for elements with IDs (fixes bug #503).

Fix cross-reference anchor placement in figures, images, literal-blocks, tables, and (sub)titles.

Simplify code for images nested in reference or figure elements.

[pierre]

Looks like mercurial fails to build doc with docutils-0.22.2.

Found a patch in a source rpm of SUSE tumbleweed (​https://download.opensuse.org/source/tumbleweed/repo/oss/src/mercurial-7.1.1-2.1.src.rpm). Weirdly, although debian has switched to docutils-0.22, they don't provide a patch for mercurial (guess they have not rebuilt it since the change). fedora, and arch don't seem to have switched to docutils-0.22.

[pierre]

Taking this, but seems harder than I thought: the API has changed a lot between 0.21 and 0.22.

[pierre]

smartypants (docutils used for tests) and json-glib (docutils used for man pages) seem ok.

[pierre]

Tested gtk4, librsvg, gdk-pixbuf, and libdrm. Man pages are correctly generated with docutils-0.22. Pango did not mention docutils, but it can use it, and rendering is ok. On a side note, we have several gnome packages that could use docutils for man pages, but we do not provide instructions, and we don't mention docutils in optional dependencies. I also tested nghttp2 with sphinx, and rendering is ok.

[pierre]

mercurial problem reported upstream, waiting for answer: ​https://foss.heptapod.net/mercurial/mercurial-devel/-/issues/10031

[Xi Ruoyao]

Replying to pierre:

mercurial problem reported upstream, waiting for answer: ​https://foss.heptapod.net/mercurial/mercurial-devel/-/issues/10031

Regarding the roman module removal, sphinx has moved to roman_numerals. See ​https://github.com/sphinx-doc/sphinx/pull/13131 (already included in the sphinx version in the book).

[pierre]

Replying to Xi Ruoyao:

Replying to pierre:

mercurial problem reported upstream, waiting for answer: ​https://foss.heptapod.net/mercurial/mercurial-devel/-/issues/10031

Regarding the roman module removal, sphinx has moved to roman_numerals. See ​https://github.com/sphinx-doc/sphinx/pull/13131 (already included in the sphinx version in the book).

Oh, thanks for the pointer! It seems the interface to docutils.utils._roman_numerals is the same as the one to roman_numerals from the roman-numerals-py package (which is in the book). Not sure whether mercurial would want to use the docutils one: they could move to use the one from roman-numerals-py and not have to check for docutils version.

[pierre]

Well, actually, roman numbers are not needed for mercurial manual pages. I'll put a sed removing all try import from hgmanpage.py, as a workaround for now.

[pierre]

Fixed at <sha:3526f069cb>

[Bruce Dubbs]

Milestone renamed