Stop accepting the DESTINATION positional argument in Docutils 1.0. Use --output=DESTINATION (cf. the "output_path" configuration setting) or output redirection.
Accept the short option -o for --output in Docutils 1.0
Drop the name attribute from nodes in Docutils 1.0.
Use the %tbl.table.att parameter entity instead of %bodyattto customize the
element's attribute list in Docutils 1.0.
The element's first child () will become mandatory in Docutils 1.0.
The "rst" parser will warn if a "figure" directive is missing both caption and legend in Docutils 1.0.
The "rst" parser will use elements for inline targets in Docutils 1.0.
elements with content will be deprecated in Docutils 1.0 and invalid in Docutils 2.0.
To match the definition in the "Exchange Table Model", the"colwidth" attribute will be stored as a str (instead of numerical) value in Python element instances in Docutils 1.0. Proportional values will be stored with unit "*" in Docutils 2.0. The default unit will change to "pt" in Docutils 3.0.
The <doctest_block> element will be deprecated in Docutils 1.0. The rST parser will handle a doctest block similar to a "code" directive with language "pycon" (Python console) and generate a <literal_block>.
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, orget_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"[1] and adapt CSS stylesheets in Docutils 1.0.
Remove use_verbatim_when_possible setting (use literal_block_env: verbatim) in Docutils 2.0.
The default length unit will change from "bp" (DTP point) to "px" (pixel unit) in Docutils 1.0.
"manpage" writer:
Change default of the text_references setting to False in Docutils 1.0.
"odt" writer:
Align adjustment of relative image paths with the behaviour of HTML and LaTeX writers: assume them relative to the output directory (as required for image references in HTML), not the source directory.
Remove utils.decode_path() and utils.get_stylesheet_reference()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 the "TransformSpec.unknown_reference_resolvers" hook chain in Docutils 1.0. Use a transform, see transforms.references.CitationReferences for an example.
Remove the internal attribute nodes.Targetable.indirect_reference_namein Docutils 1.0. (Was required for MoinMoin <= 1.9.)
Don't call transforms.references.DanglingReferences andtransforms.references.DanglingReferencesVisitor in Docutils 1.0; remove them in Docutils 2.0. [rationale]
Remove parsers.rst.roles.set_classes() andparsers.rst.roles.normalized_role_options()(obsoleted by parsers.rst.roles.normalize_options()) in Docutils 2.0.
Remove the "rawsource" argument from nodes.Text.__init__()in Docutils 2.0.
Remove the internal attributes nodes.Element.known_attributes,nodes.Element.basic_attributes, and nodes.Element.local_attributes, 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 ofcore.Publisher.__init__() and the core.publish_*() convenience functions as well as the "parser_name" argument of Reader.__init__()in Docutils 2.0. Since Docutils 0.22, you may use "reader", "parser", and "writer" arguments for component names as well as instances.
Remove states.RSTStateMachine.memo.section_bubble_up_kludge,states.RSTStateMachine.memo.section_level,states.RSTState.title_inconsistent(), and states.Line.eofcheckin Docutils 2.0. Ignored since Docutils 0.22.
Remove frontend.OptionParser, frontend.Option, frontend.Values,frontend.store_multiple(), and frontend.read_config_file() when migrating to argparse in Docutils 2.0 or later.
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.)
Change the default priority of the universal.SmartQuotes transformfrom 855 (very late) to 510 (main) in Docutils 1.0.
Move math format conversion from docutils/utils/math (called from docutils/writers/_html_base.py) to a transform.
If the environment variable SOURCE_DATE_EPOCH is set, the "date"directive and the timestamp inserted by the "datestamp" configuration setting will use its value instead of the current time to support reproducible builds in Docutils 1.0. [2]
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.
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 \hyperrefcommand. 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.
HTML5:
Unitless image size measures are written as "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.
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.xmlor 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 withuri2path() auxiliary method. Provisional.
Removed objects
core.Publisher.setup_option_parser()
internal, obsolete,
frontend.ConfigParser.get_section()
obsoleted by the configparser's "Mapping Protocol Access",
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".
Provide rst2* "console_scripts" entry points(without the .py extension) instead of installing therst2*.py front end tools in the binary PATH. [3] Exceptions: rstpep2html.py and rst2odt_prepstyles.py: * Use docutils --reader=pep --writer=pep_html for a PEP preview. [4] * Use python -m docutils.writers.odf_odt.prepstylesto strip the page size from an ODT writer stylesheet.
reStructuredText:
Use the same CSV format for the :header: option and the main data of the "csv-table" directive.
New option "loading" for the "image" directive. Sets the new attribute loading of the doctree element.
Configuration changes:
New configuration setting root_prefix. Configurable root directory for included files.
New configuration setting sources for the "buildhtml.py" application.
Simpler and more secure input_encoding default behaviour: Do not use the locale encoding as fallback if Python is started inUTF-8 mode. Stop using "latin1" as second fallback. Remove BOM (U+FEFF ZWNBSP at start of data) only if the input_encodingconfiguration setting is None, '', 'utf-8-sig', 'utf-16', or 'utf-32'. Do not remove other ZWNBSPs.
Output changes: HTML5: Stop setting the "footnote-reference" class value for footnote references. Use the CSS selector [role="doc-noteref"](works since Docutils 0.18, see minimal.css for examples). Fix MathML rendering problems in Chrome/Chromium based browsers. Embed SVG images as
New files: docutils/writers/html5_polyglot/italic-field-names.css Alternative style for Docutils field-lists.
Removed files: install.py, setup.py Metadata is now stored in pyproject.toml, supported by pip since version 19.0 (2019-01-22). See README for installation alternatives.
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 configuration setting "output". Obsoletes the 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 /.
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.
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.)
During identifier normalization, leading number and hyphen characters are no longer stripped from a reference name, if theid_prefix setting is non-empty. Example: with --id-prefix="DU-", a section with title "34. May" now gets the identifier key DU-34-may instead of DU-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
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 element (deprecated in HTML5).
Use STIX fonts if available. LaTeX: legacy_class_functions setting default changed to "False", admonitions are now environments.
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 indocutils/utils/math/math2html.py anddocutils/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.
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".
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.
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.
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.
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).
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, anddocutils/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 tag for inline "code", do not drop nested inline nodes (syntax highlight tokens).
Customizable MathJax URL (based on patch by Dmitry Shachnev).
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 withsetup.py install under Python 3, remove the spurioustest/ and tools/ directories in the site library root.
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 .. image:: image.png 📛 image name as a short form of .. _image name: .. image:: 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.
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" option of "figure" and "image" directives.
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).
Bugfix: The "align" argument of a figure now works as documented (aligning the figure, not its contents).
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 Directiveshow-to.
Allow + and : in reference names requested for citations.
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 andpublish_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).
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.)