Docutils | Overview | About | Users | Reference | Developers

Docutils Release Notes

Contact:
grubert@users.sourceforge.net
Maintainer:

docutils-develop@lists.sourceforge.net

Date:
$Date$
Revision:
$Revision$
Web site:

https://docutils.sourceforge.io/

This document summarizes the major changes in previous and upcoming releases. For a more detailed list of changes, please see the Docutils HISTORY.

Future changes

Command line interface

  • The command-line usage pattern will change:

    - COMMAND [OPTIONS] [SOURCE [DESTINATION]]
    + COMMAND [OPTIONS] [SOURCE [SOURCE2 [...]]] [>DESTINATION]
    • Stop accepting the DESTINATION positional argument in Docutils 1.0. Use output redirection or the option --output=DESTINATION (available since Docutils 0.20).

    • Accept more than one source document and the short option -o for --output in Docutils 2.0

    For the rationale, see https://clig.dev/#arguments-and-flags.

Document Tree / Docutils DTD

  • Do not lowercase reference names in the refname attribute (matching hyperlinks, footnotes, and citations remains case insensitive), and drop the name attribute from <reference> nodes in Docutils 1.0.

  • Use the %tbl.table.att parameter entity instead of %bodyatt to customize the <table> element's attribute list in Docutils 1.0.

  • The <footnote> element's first child (<label>) will become mandatory in Docutils 1.0.

Writers

  • The default HTML writer will change in Docutils 2.0:

    The rst2html front end and get_writer_by_name('html') select "html4css1" now and will select "html5" in Docutils 2.0 and later.

    • Use rst2html4, docutils --writer=html4, or get_writer_by_name('html4') if you depend on stability of the generated HTML code, e.g. because you use a custom style sheet or post-processing that may break otherwise.

    • Use rst2html5, docutils or get_writer_by_name('html5') if you want a HTML5 document.

  • "html5" writer:

    • Move attribution behind the blockquote to comply with the "HTML living standard". (The now retired HTML5 W3C recommendation allows <cite> elements inside a blockquote.)

    • Unitless image :width: and :hight: values and dimensions read from the image due to a :scale: option will be written as "width" and "hight" attributes instead of "style" rules to allow specification of the aspect ratio to prevent jank when loading images without overwriting an image size set in a CSS stylesheet in Docutils 0.22 (cf. feature-requests:102). The current behaviour is kept for dimensions with units, so users may specify, e.g. :width: 50px instead of :width: 50 to override CSS stylesheet rules.

    • Change the default value of the initial_header_level setting to None (<h2> if there is a document title, else <h1>) in Docutils 1.0.

    • Remove option --embed-images (obsoleted by "image_loading") in Docutils 2.0.

  • "latex2e" writer:

Misc

  • Remove io.BinaryFileOutput and core.publish_cmdline_to_binary() in Docutils 0.24.

  • Remove parsers.rst.directives.CSVTable.HeaderDialect in Docutils 1.0.

  • Remove support for the recommonmark parser in Docutils 1.0. Recommonmark is unmaintained since 2021 and deprecated in favour of the MyST parser.

  • Remove the input encoding auto-detection code in Docutils 1.0.

  • Remove parsers.rst.roles.set_classes() and parsers.rst.roles.normalized_role_options() in Docutils 1.0.

  • Remove the "rawsource" argument from nodes.Text.__init__() in Docutils 2.0.

  • Remove the deprecated attributes nodes.Element.known_attributes, nodes.Element.basic_attributes, and nodes.Element.local_attributes, in Docutils 2.0.

  • Drop support for old-format configuration files in Docutils 2.0.

  • Remove the --html-writer option of the buildhtml.py application (obsoleted by the "writer" setting since Docutils 0.18) in Docutils 2.0.

  • Remove the "reader_name", "parser_name", and "writer_name" arguments of core.Publisher.__init__() and the core.publish_*() convenience functions in Docutils 2.0. Since Docutils 0.22, you may use "reader", "parser", and "writer" arguments for component names as well as instances.

  • Revise the String I/O interface used by the publish_string() and publish_from_doctree() publisher convenience functions. (In Python 3, name and behaviour no longer match.)

  • Move math format conversion from docutils/utils/math (called from docutils/writers/_html_base.py) to a transform.

Release 0.22b.dev (unpublished)

Document Tree / Docutils DTD
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.)

Output changes
"manpage" writer:

Don't UPPERCASE section headings.

"null" writer:

output changed from None to the empty string.

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

"latex" writer:

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 "ref*").

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.

Removed objects
docutils.core.Publisher.setup_option_parser()

internal, obsolete,

docutils.frontend.OptionParser.set_defaults_from_dict()

obsolete,

docutils.nodes.Element.set_class()

obsolete, append to Element['classes'] directly,

docutils.parsers.rst.directives.tables.CSVTable.decode_from_csv()

not required with Python 3,

docutils.parsers.rst.directives.tables.CSVTable.encode_from_csv()

not required with Python 3,

docutils.transforms.writer_aux.Compound

not used since Dec 2010,

docutils.utils.error_reporting

obsolete in Python 3,

docutils.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".

Removed files
tools/rst2odt_prepstyles.py

Obsoleted by docutils.writers.odf_odt.prepstyles.

Bugfixes and improvements (see HISTORY).

Release 0.21.2 (2024-04-23)

Release 0.21.1 (2024-04-10)

Add missing metadata files to sdist. No changes to the code.

Release 0.21 (2024-04-09)

Release 0.20.1 (2023-05-17)

Bugfix release. See HISTORY for details.

Release 0.20 (2023-05-04)

Release 0.19 (2022-07-05)

(Release 0.19b1 (2022-06-21))

Release 0.18.1 (2021-12-23)

Release 0.18 (2021-10-26)

Release 0.17.1 (2021-04-16)

Release 0.17 (2021-04-03)

Release 0.16 (2020-01-12)

Docutils 0.16.x supports Python 2.7 and Python >= 3.5 natively, without the use of the 2to3 tool.

Release 0.15 (2019-07-20)

Docutils 0.15.x is compatible with Python versions 2.6, 2.7 and 3.3 to 3.5.

Release 0.14 (2017-08-03)

Release 0.13.1 (2016-12-09)

Release 0.12 (2014-07-06)

Small changes only, release current state

Release 0.11 (2013-07-22)

Release 0.10 (2012-12-16)

Docutils 0.10 is compatible with Python versions from 2.4 to 3.2.

Release 0.9.1 (2012-06-17)

Release 0.9 (2012-05-02)

Release 0.8.1 (2011-08-30)

Release 0.8 (2011-07-07)

Internationalization:

Components:

Release 0.7 (2010-07-07)

Components:

General:

Release 0.6 (2009-10-11)

Docutils 0.6 is compatible with Python versions from 2.3 up to 2.6 and convertible to 3.1 code.

Release 0.5 (2008-06-25)

Components:

reStructuredText:

Documentation:

Internationalization:

General:

Release 0.4 (2006-01-09)

Components:

reStructuredText:

Internationalization:

Documentation:

General:

Release 0.3.9 (2005-05-26)

Release 0.3.7 (2004-12-24)

Release 0.3.5 (2004-07-29)