Docutils Release Notes

Future changes

Release 0.21 (unpublished)

• Drop support for Python 3.7 and 3.8.

• Provide rst2* "console_scripts" entry points (without the .py extension) instead of installing the rst2*.py front end tools in the binary PATH. [1]

  Exceptions: rstpep2html.py and rst2odt_prepstyles.py:

  • Use docutils --reader=pep --writer=pep_html for a PEP preview. [2]

  • Use python -m docutils.writers.odf_odt.prepstyles to strip the page size from an ODT writer stylesheet.

• Simpler and more secure input encoding default behaviour:

  Do not use the locale encoding as fallback if Python is started in UTF-8 mode. Stop using "latin1" as second fallback.

  Remove BOM (U+FEFF ZWNBSP at start of data) only if the input_encoding configuration setting is None, '', 'utf-8-sig', 'utf-16', or 'utf-32'. Do not remove other ZWNBSPs.

• "html5" writer: Stop setting the "footnote-reference" class value for footnote references. You can use the CSS selector [role="doc-noteref"] since Docutils 0.18 (see minimal.css for examples).

• Use the same CSV format for the :header: option and the main data of the "csv-table" directive.

• Removed objects:

  • nodes.reprunicode and nodes.ensure_str() (not required with Python 3), utils.Reporter.set_conditions() (obsolete) core.Publisher.setup_option_parser() (internal, obsolete)

  • File install.py. See README.txt for alternatives.

Release 0.20.1 (2023-05-17)

Bugfix release. See HISTORY for details.

Release 0.20 (2023-05-04)

• General

  • Support Python 3.11 (patch #198 by Hugo van Kemenade).

• Output changes:

  HTML5:

  Use dpub-ARIA role "doc-footnote" (instead of ARIA role "note") for footnotes.

  LaTeX:

  Do not load the inputenc package in UTF-8 encoded LaTeX sources. (UTF-8 is the default encoding for LaTeX2e since 2018).

• Configuration changes:

  • Settings in the [latex2e writer] configuration file section are now ignored by the "xetex" writer. Place common settings in section [latex writers].

  • New command line setting output. Obsoletes the <destination> positional argument (cf. future changes).

• utils.find_file_in_dirs() now returns a POSIX path also on Windows; utils.get_stylesheet_list() no longer converts \ to /.

• docutils/languages/ docutils/parsers/rst/languages/

  • Support Ukrainian. Patch by Dmytro Kazanzhy.

• test/coverage.sh

  • Removed. Use the coverage.py project instead, coverage run test/alltests.py and coverage report.

• tools/

  • Moved quicktest.py to tools/dev/.

• Bugfixes and improvements (see HISTORY).

Release 0.19 (2022-07-05)

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

• Drop support for Python 2.7, 3.5, and 3.6.

• Output changes:

  HTML5:

  Wrap groups of footnotes in an <aside> for easier styling.

  The CSS rule .footnote-list { display: contents; } can be used to restore the behaviour of custom CSS styles.

• After package installation, the CLI commands python -m docutils and docutils start the generic command line front end tool.

• Support parsing "Markdown" input with 3rd party parsers myst, pycmark, or recommonmark.

• The default values for the "pep-references", "rfc-base-url", and "python-home" configuration settings now use the "https:" scheme. The PEP-writer template's header is updated to fix links and resemble the header of official PEPs.

• Various bugfixes and improvements (see HISTORY).

Release 0.18.1 (2021-12-23)

• nodes.Node.traverse() returns a list again to restore backwards compatibility (fixes bug #431). Use nodes.Node.findall() to get an iterator.

• re-add module parsers.rst.directives.html (stub, emits deprecation warning and loads "Meta" directive from its new place at parsers.rst.directives.misc.)

• Small bugfixes (see HISTORY).

Release 0.18 (2021-10-26)

• Output changes:

  Identifiers:

  • During identifier normalization, leading number and hyphen characters are no longer stripped from a reference name, if the id_prefix setting is non-empty.

    Example:

    with --id-prefix="DU-", a section with title "34. May" currently gets the identifier key DU-may and after the change the identifier key DU-34-may.

  • The default value for the auto_id_prefix setting changed to %: "use the tag name as prefix for auto-generated IDs". Set auto_id_prefix to id for unchanged auto-IDs.

  HTML5:

  • Use the semantic tag <aside> for footnote text and citations, topics (except abstract and toc), admonitions, and system messages. Use <nav> for the Table of Contents.

  • Make "auto" table column widths the default: Only specify column widths, if the "widths" option is set and not "auto". The table-style setting "colwidths-grid" restores the current default.

  • Items of a definition list with class argument "details" are converted to details disclosure elements. Example:

    ..class:: details
    
    Summary
      This additional information should be hidden.

  • Do not add "compound-first", "compound-middle", or "compound-last" to elements nested in a compound. Use child selector and ":first-child", ":last-child" pseudo classes instead.

  • Use class value "backrefs" instead of "fn-backref" for a span of back-references.

  • Write footnote brackets and field term colons to HTML, so that they are present also without CSS and when copying text.

  • Move space character between section number and heading into "sectnum" span.

  math-output: html

  • Support more commands, fix mapping of commands to Unicode characters.

  • Scale variable sized operators and big delimiters with CSS.

  • Don't use <tt> element (deprecated in HTML5).

  • Use STIX fonts if available.

  LaTeX:

  legacy_class_functions setting default changed to "False", admonitions are now environments.

• New standard Docutils doctree node: <meta>.

• New configuration settings:

  • [latex writers] legacy_column_widths and

  • [html5 writer] image_loading.

• Removed files: iepngfix.htc and blank.gif (IE 6 workaround for s5_html).

• Removed sub-module: parsers.rst.directives.html (reversed in release 0.18.1).

• Removed function: utils.unique_combinations() (obsoleted by itertools.combinations()).

• Removed attributes:

  • HTMLTranslator.topic_classes: check node.parent.classes instead.

  • nodes.Text.rawsource: we store the null-escaped text in Text nodes since 0.16 so there is no additional information in the rawsource.

• Major refactoring and fixes/additions in docutils/utils/math/math2html.py and docutils/utils/math/latex2mathml.py (mathematical notation in HTML, cf. LaTeX syntax for mathematics).

• nodes.Node.traverse() returns an iterator instead of a list (reversed in release 0.18.1).

• Various bugfixes and improvements (see HISTORY).

  Fix spelling errors in documentation and docstrings. Thanks to Dimitri Papadopoulos.

Release 0.17.1 (2021-04-16)

• Bug fixes (for details see the Docutils HISTORY).

Release 0.17 (2021-04-03)

• Numerous bug fixes and improvements (for details see the Docutils HISTORY).

• Installing with setup.py now requires setuptools. Alternatively, install with pip.

• The generic command line front end tool docutils-cli.py allows the free selection of reader, parser, and writer components.

• Support Arabic language.

• New, experimental wrapper to integrate the recommonmark Markdown parser for use with Docutils. Currently only tested with recommonmark version 0.4.0.

• HTML5 writer:

  • New option embed_images.

  • Use semantic tags (for details see the Docutils HISTORY).

  • Change the initial_header_level setting's default to "2", as browsers use the same style for <h1> and <h2> when nested in a section.

  • New optional style responsive.css, adapts to different screen sizes.

  • Move non-essential styling from minimal.css to plain.css rsp. responsive.css.

  • Show code line numbers as pseudo-elements so they are skipped when copying the code block from the page.

• LaTeX writer:

  • New configuration setting legacy_class_functions.

  • The special value "auto" for the graphicx_option setting is no longer supported (it never worked for xetex/luatex).

  • Styling commands using the legacy \docutilsrole prefix are now ignored. Use \DUrole.

  • Most helper commands and element definitions are now defined in the LaTeX package docutils.sty and only inserted in the document preamble if the stylesheet setting does not lists "docutils".

  • Remove legacy LaTeX stylesheet docutils-05-compat.sty.

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.

• reStructuredText:

  • Keep backslash escapes in the document tree. This allows, e.g., escaping of author-separators in bibliographic fields.

• LaTeX writer:

  • Informal titles of type "rubric" default to bold-italic and left aligned.

  • Deprecate \docutilsrole prefix for styling commands: use \DUrole instead.

  • Fix topic subtitle.

  • Add "latex writers" to the config_section_dependencies.

  • Ignore classes for rubric elements (class wrapper interferes with LaTeX formatting).

• tools/buildhtml.py

  • New option --html-writer allows to select "html" (default), "html4" or "html5" (deprecated in favour of the "writer" setting in Docutils 0.18).

• docutils/io.py

  • Remove the handle_io_errors argument from io.FileInput/Output.

• docutils/nodes.py

  • If auto_id_prefix ends with "%", this is replaced with the tag name.

• Various bugfixes and improvements (see HISTORY).

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.

• reStructuredText:

  • Allow embedded colons in field list field names (before, tokens like :this:example: were considered ordinary text).

  • Fixed a bug with the "trim" options of the "unicode" directive.

• languages: Added Korean localisation (ko).

Release 0.14 (2017-08-03)

• docutils/docs/ref/docutils.dtd:

  • Enable validation of Docutils XML documents against the DTD:

• docutils/parsers/rst/:

  • Added functionality: escaped whitespace in URI contexts.

  • Consistent handling of all whitespace characters in inline markup recognition. (May break documents that relied on some whitespace characters (NBSP, ...) not to be recognized as whitespace.)

• docutils/utils/smartquotes.py:

  • Update quote definitions for et, fi, fr, ro, sv, tr, uk.

  • Add quote definitions for hr, hsb, hu, lv, sh, sl, sr.

  • Differentiate apostrophe from closing single quote (if possible).

  • Add command line interface for stand-alone use (requires 2.7).

• docutils/writers/_html_base:

  • Provide default title in metadata.

  • The MathJax CDN shut down on April 30, 2017. For security reasons, we don't use a third party public installation as default but warn if math-output is set to MathJax without specifying a URL. See math-output for details.

• docutils/writers/html4css1:

  • Respect automatic table column sizing.

• docutils/writers/latex2e/__init__.py

  • Handle class arguments for block-level elements by wrapping them in a "DUclass" environment. This replaces the special handling for "epigraph" and "topic" elements.

• docutils/writers/odf_odt:

  • Language option sets ODF document's default language

  • Image width, scale, ... set image size in generated ODF.

• tools/

  • New front-end rst2html4.py.

Release 0.13.1 (2016-12-09)

• docutils/writers/html5_polyglot

  • New HTML writer generating HTML 5.

• tools/

  • New front-end rst2html5.py.

• languages: persian/farsi (fa) and latvian (la) mappings.

• change default base url for :rfc: to http://tools.ietf.org/html/

• tables accept widths, a list and align

• latex2e: Fix admonition width, remove deprecated options, better tablewidth auto, ...

• rst.el: The problem with electric-indent-mode has been fixed.

Release 0.12 (2014-07-06)

Small changes only, release current state

Release 0.11 (2013-07-22)

• General

  • Apply [ 2714873 ] Fix for the overwriting of document attributes.

  • Support embedded aliases within hyperlink references.

  • Fix [ 228 ] try local import of docutils components (reader, writer, parser, language module) before global search.

• docutils/parsers/rst/directives/tables.py

  • Fix [ 210 ] Python 3.3 checks CVS syntax only if "strict" is True.

• docutils/writers/html4css1/__init__.py - Fix [ 3600051 ] for tables in a list, table cells are not compacted. - New setting stylesheet_dirs (see above).

  Now, it is easy to add a custom stylesheet to Docutils' default stylesheet with, e.g., --stylesheet_path='html4css1.css, mystyle.css'

  Changed behaviour of the default settings:

  if there is a file html4css1.css in the working directory of the process at launch, it is used instead of the one provided by Docutils in the writer source directory.

  • New default for math-output: HTML math.css.

  • Avoid repeated class declarations in html4css1 writer (modified version of patch [ 104 ]).

• docutils/writers/latex2e/__init__.py

  • Drop the simple algorithm replacing straight double quotes with English typographic ones. Activate the SmartQuotes transform if you want this feature.

  • New setting stylesheet_dirs: Comma-separated list of directories where stylesheets are found. Used by stylesheet_path when expanding relative path arguments.

• docutils/writers/manpage.py

  • Fix [3607063] handle lines starting with a period.

  • Fix option separating comma was bold (thanks to Bill Morris).

Release 0.10 (2012-12-16)

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

• General:

  • SmartQuotes transform for typographic quotes and dashes.

  • docutils/math, docutils/error_reporting.py, and docutils/urischemes.py moved to the utils package. Code importing these modules needs to adapt, e.g.:

    try:
        import docutils.math as math
    except ImportError:
        import docutils.utils.math as math

  • enhanced math and error handling.

• docutils/io.py

  • FileInput/FileOutput: no system-exit on IOError. The handle_io_errors argument is ignored.

• docutils/writers/html4css1/__init__.py

  • Use <code> tag for inline "code", do not drop nested inline nodes (syntax highlight tokens).

  • Customizable MathJax URL (based on patch by Dmitry Shachnev).

  • No line break after opening inline math tag.

• docutils/writers/latex2e/__init__.py, docutils/writers/xetex/__init__.py

  • Fix section numbering by LaTeX.

• docutils/writers/s5_html/__init__.py

  • Fix [ 3556388 ] Mathjax does not work with rst2s5.

Release 0.9.1 (2012-06-17)

• General:

  Several fixes for Python 3 usage.

• docutils/setup.py

  • Fix [ 3527842 ]. Under Python 3, converted tests and tools were installed in the PYTHONPATH. Converted tests are now stored in docutils/test3/, tools no longer need conversion.

    If you installed one of Docutils versions 0.7 ... 0.9 with setup.py install under Python 3, remove the spurious test/ and tools/ directories in the site library root.

Release 0.9 (2012-05-02)

• General:

  • reStructuredText "code" role and directive with syntax highlighting by Pygments.

  • "code" option of the "include" directive.

  • Fix [ 3402314 ] allow non-ASCII whitespace, punctuation characters and "international" quotes around inline markup.

  • Fix handling of missing stylesheets.

• setup.py

  • Fix [ 2971827 ] and [ 3442827 ] extras/roman.py moved to docutils/utils/roman.py

• docutils/utils.py -> docutils/utils/__init__.py

  • docutils.utils is now a package (providing a place for sub-modules)

• docutils/writers/html4css1/__init__.py

  • change default for math-output setting to MathJax

• docutils/writers/latex2e/__init__.py

  • Support the abbreviation and acronym standard roles.

  • Record only files required to generate the LaTeX source as dependencies.

  • Use \setcounter{secnumdepth}{0} instead of *-versions when suppressing LaTeX section numbering.

Release 0.8.1 (2011-08-30)

• General:

  • Fix [ 3364658 ] (Change last file with Apache license to BSD-2-Clause) and [ 3395920 ] (correct copyright info for rst.el).

• docutils/writers/latex2e/__init__.py

  • Clean up Babel language setting. Restores Sphinx compatibility.

Release 0.8 (2011-07-07)

• COPYING:

  • Some additions to the Docutils core are released under the 2-Clause BSD license.

• General:

  • Handle language codes according to BCP 47.

  • If the specified language is not supported by Docutils, warn and fall back to English.

  • Math support: reStructuredText "math" role and directive, math and math_block doctree elements.

  • Orphaned "python" reader and "newlatex2e" writer moved to the sandbox.

• reStructuredText:

  • most directives now support a "name" option that attaches a reference name. So you can write

    .. figure:: image.png
       :name: figure name

    as a short form of

    .. _figure name:
    
    .. figure:: image.png

Internationalization:

• Added lithuanian mappings.

Components:

• HTML writer:

  • New setting "math-output" with support for HTML, MathML, and LaTeX.

• LaTeX2e writer:

  • Convert image URI to a local file path.

  • Apply [ 3148141 ] fix multicolumn support when a colspanning cell has more than one paragraph (Wolfgang Scherer).

• XeTeX writer:

  • New writer generating LaTeX code for compiling with xelatex.

    XeTeX uses unicode and modern font technologies.

• and fixes and enhancements here and there.

Release 0.7 (2010-07-07)

Components:

• HTML writer:

  • Support SVG and SWF images (thanks to Stefan Rank).

  • Generate valid XHTML for centered images with targets. Use CSS classes instead of "align" tags for image alignment.

• LaTeX2e writer:

  • Use the \url command for URLs (breaks long URLs instead of writing into the margin).

  • Preserve runs of spaces in 'inline literals'.

  • Deprecate figure_footnotes setting.

  • Rename use_latex_footnotes setting to docutils_footnotes.

  • New latex_preamble setting.

  • Use PDF standard fonts (Times/Helvetica/Courier) as default.

  • hyperref package called with unicode option (see the hyperref config tips for how to override).

  • Drop the special output_encoding default ("latin-1"). The Docutils wide default (usually "UTF-8") is used instead.

• manpage writer:

  • Titles level 1, that is .SH, always uppercase.

  • Apply patch from mg: literal text should be bold in man-pages.

General:

• io.FileInput opens files as text files with universal newline support (mode "rU", configurable with the new optional argument "mode").

• setup.py:

  • Python 3 support: copy test/ and tools/ to the build-dir and convert Python sources with 2to3.

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.

• reStructuredText:

  • Allow length units for all length specifications.

  • Allow percent sign in "scale" argument of "figure" and "image" directives.

  • Bugfix: The "figalign" argument of a figure now works as intended (aligning the figure not its contents).

  • Align images with class "align-[right|center|left]" (allows setting the alignment of an image in a figure).

  • Hard tabs in literal inclusions are replaced by spaces. This is configurable via the new "tab-width" option of the "include" directive (a negative tab-width prevents tab expansion).

• HTML writer:

  • --stylesheet and --stylesheet-path options now support a comma separated list of stylesheets.

• LaTeX2e writer:

  • New defaults: - font-encoding: "T1" (formerly implicitly set by 'ae'). - use-latex-toc: true (ToC with page numbers). - use-latex-footnotes: true (no mixup with figures). - Float placement defaults to "here definitely" (configurable). - Align of image in a figure defaults to 'center'. - Use class defaults for page margins ('typearea' now optional).

  • Support LaTeX packages as --stylesheet arguments.

  • Use bp for lengths without unit or unit pt, do not convert px to pt.

  • Do not use 'ae' and 'aeguill' packages if font-encoding is set to ''.

  • Set sub- and superscript role argument as text not math.

  • Support custom roles based on standard roles.

  • Load packages and define macros only if required in the document.

  • All Docutils specific LaTeX macros are prefixed with DU.

  • Better conformance to Docutils specifications with "use_latex_toc".

  • If 'sectnum_xform' is False, the 'sectnum' directive triggers section numbering by LaTeX.

  • Use default font in admonitions and sidebar.

  • Typeset generic topic as "quote with title".

  • Use template (file and configuration option).

  • Render doctest blocks as literal blocks (indented).

• ODT writer:

  • moved from sandbox to Doctutils core.

• manpage writer:

  • moved from sandbox to Doctutils core.

Release 0.5 (2008-06-25)

Components:

• HTML writer.

  • Dropped all name attributes of a elements (id is universally supported now).

• LaTeX2e writer:

  • Better bibTeX citation support.

  • Add --literal-block-env

• PEP writer:

  • Changed to support new python.org website structure and pep2pyramid.py.

reStructuredText:

• Changed the directive API to a new object-oriented system. (Compatibility for the old, functional-style directive interface is retained.) See the updated Creating reStructuredText Directives how-to.

• Allow + and : in reference names requested for citations.

Documentation:

• Added Deploying Docutils Securely

Internationalization:

• Added hebrew mappings.

General:

• Configuration files are now assumed and required to be UTF-8-encoded.

• Added docutils/writers/html4css1/template.txt.

• Enhance emacs support.

Release 0.4 (2006-01-09)

Components:

• Added an S5/HTML writer and the rst2s5.py front end: multi-platform, multi-browser HTML slide shows.

• The newlatex2e writer is nearing completion.

• Added a DocTree reader, publish_doctree and publish_from_doctree convenience functions, for document tree extraction and reprocessing.

reStructuredText:

• Added directives: "container" (generic block-level container), "default-role" (role used for `backtick` syntax), "title" (document title metadata), and "date" (generate the current local date, for substitution definitions).

• Length units are now supported for image sizes.

• Added standard definition files for special characters etc.

Internationalization:

• Added Japanese and Simplified Chinese language mappings, and support for double-width CJK-characters in tables and section titles.

Documentation:

• Added a guide for distributors (package maintainers) and a guide for developers.

General:

• Added significant Emacs support for reST.

• Added a --strip-comments option.

• --embed-stylesheet is now the default for the HTML writer (rather than --link-stylesheet).

Release 0.3.9 (2005-05-26)

• Added "file_insertion_enabled" and "raw_enabled" settings.

• Added auto-enumerated lists.

• Added "header" and "footer" directives.

• Added "list-table" directive.

• Added support for section subtitles.

• Added "field_name_limit" and "option_limit" settings to HTML writer.

• Added "cloak_email_addresses" setting to HTML writer.

• UTF-8 BOMs are now removed from the input stream.

Release 0.3.7 (2004-12-24)

• A special "line block" syntax has been added. (Also see the quick reference.)

• Empty sections are now allowed.

• A "raw" role has been added.

• The LaTeX writer now escapes consecutive dashes (like "--" or "---") so that they are no longer transformed by LaTeX to en or em dashes. (Please see the FAQ for how to represent such dashes.)

• A dependency recorder has been added.

• A directive has been added for compound paragraphs.

Release 0.3.5 (2004-07-29)

• Improved, extended and reorganized the documentation.

• Added "csv-table" directive.