David Goodger
Transforms change the document tree in-place, add to the tree, or prune it. Transforms resolve references and footnote numbers, process interpreted text, and do other context-sensitive processing. Each transform is a subclass of docutils.transforms.Transform.
Most transforms are added by components, others (e.g. parts.Contents) are added by the parser if a corresponding directive is found in the document.
To add a transform, components (objects inheriting from docutils.Component like Readers, Parsers, Writers, Input, Output) overwrite the get_transforms() method of their base class. After the Reader has finished processing, the Publisher calls Transformer.populate_from_components() with a list of components and all transforms returned by the component's get_transforms() method are stored in a Transformer object attached to the document tree.
For more info about transforms and the Transformer object, see also PEP 258. [1]
Transforms Listed in Priority OrderTransform classes each have a default_priority attribute which is used by the Transformer to apply transforms in order (low to high). The default priority can be overridden when adding transforms to the Transformer object.
Transform: module.Class
Added By
Priority
misc.ClassAttribute
"class" (d/p)
210
references.Substitutions
standalone (r), pep (r)
220
references.PropagateTargets
standalone (r), pep (r)
260
frontmatter.DocTitle
standalone (r)
320
frontmatter.DocInfo
standalone (r)
340
frontmatter.SectSubTitle
standalone (r)
350
peps.Headers
pep (r)
360
peps.Contents
pep (r)
380
universal.StripClassesAndElements
writers (w)
420
references.AnonymousHyperlinks
standalone (r), pep (r)
440
references.IndirectHyperlinks
standalone (r), pep (r)
460
peps.TargetNotes
pep (r)
520
references.TargetNotes
peps.TargetNotes (t/p)
0
misc.CallBack
peps.TargetNotes (t/p)
1
references.TargetNotes
"target-notes" (d/p)
540
references.Footnotes
standalone (r), pep (r)
620
references.ExternalTargets
standalone (r), pep (r)
640
references.InternalTargets
standalone (r), pep (r)
660
parts.SectNum
"sectnum" (d/p)
710
parts.Contents
"contents" (d/p), peps.Contents (t/p)
720
universal.StripComments
readers (r)
740
peps.PEPZero
peps.Headers (t/p)
760
references.CitationReferences
latex2e (w)
770
components.Filter
not used
780
universal.Decorations
readers (r)
820
misc.Transitions
standalone (r), pep (r)
830
universal.Validate
parsers (p)
835
universal.ExposeInternals
readers (r)
840
references.DanglingReferences
standalone (r), pep (r), deprecated [2]
850
universal.SmartQuotes
rst (p)
855
universal.Messages
writers (w)
860
universal.FilterMessages
writers (w)
870
universal.TestMessages
DocutilsTestSupport
880
writer_aux.Compound
not used, to be removed
910
writer_aux.Admonitions
_html_base (w), latex2e (w)
920
misc.CallBack
n/a
990
Key:
(r): Reader
(w): Writer
(d): Directive
(t): Transform
(/p): Via a <pending> element
Priority
From
To
Category
0
99
immediate execution (added by another transform)
100
199
very early (non-standard)
200
299
very early
300
399
early
400
699
main
700
799
late
800
899
very late
900
999
very late (non-standard)
Transforms Added by Componentsuniversal.StripComments (
740)
universal.Decorations (
820)
universal.ExposeInternals (
840)
None
references.Substitutions (
220)
references.PropagateTargets (
260)
references.AnonymousHyperlinks (
440)
references.IndirectHyperlinks (
460)
references.Footnotes (
620)
references.ExternalTargets (
640)
references.InternalTargets (
660)
references.DanglingReferences (
850)
references.Substitutions (
220)
references.PropagateTargets (
260)
references.AnonymousHyperlinks (
440)
references.IndirectHyperlinks (
460)
references.Footnotes (
620)
references.ExternalTargets (
640)
references.InternalTargets (
660)
references.DanglingReferences (
850)
universal.SmartQuotes (855)
universal.StripClassesAndElements (
420)
universal.Messages (
860)
universal.FilterMessages (
870)
None
writer_aux.Admonitions (
920)
references.CitationReferences (
770)
writer_aux.Admonitions (920)
removes references.DanglingReferences
Note
This section is still incomplete.
See also Transforms Listed in Priority Order and the sources in docutils/transforms.
DocInfostandalone Reader
docinfo_xform (default: True)
Given a document starting [3] with a field list, the DocInfo transform converts fields with registered bibliographic field names to the corresponding document tree elements becoming child elements of the <docinfo> element (except for "dedication" and "abstract", which become <topic> elements after <docinfo>).
For example, this document fragment:
<document>
<title>
Document Title
<field_list>
<field>
<field_name>
Author
<field_body>
<paragraph>
A. Name
<field>
<field_name>
Status
<field_body>
<paragraph>
$RCSfile$
...
will be transformed to:
<document>
<title>
Document Title
<docinfo>
<author>
A. Name
<status>
frontmatter.py
...DocTitle
standalone Reader
doctitle_xform (default: True)
Under the conditions explained below, the DocTitle transform converts the document's first section title(s) to a document title and subtitle.
If the document contains a single top-level section as its first body element, [4] the top-level section's title is used as document title and default metadata title. The top-level section's contents become the document's immediate contents.
If step 1 successfully determines the document title, the transform checks for a subtitle: If the lone top-level section itself contains a single second-level section as its first element, [4] that section's title is promoted to the document's subtitle, and that section's contents become the document's immediate contents.
The transform can be disabled with the doctitle_xform configuration setting or the corresponding --no-doc-title command line option.
ExamplesThe input text
Top-Level Title =============== A paragraph.
is parsed to the following document tree:
<document>
<section names="top-level\ title">
<title>
Top-Level Title
<paragraph>
A paragraph.
The DocTitle transform converts it to:
<document names="top-level\ title" title="Top-Level Title">
<title>
Top-Level Title
<paragraph>
A paragraph.
Given this input with a lone section and sub-section:
Top-Level Title =============== Second-Level Title ~~~~~~~~~~~~~~~~~~ A paragraph.
the result after parsing and running the DocTitle transform is:
<document names="top-level\ title">
<title>
Top-Level Title
<subtitle names="second-level\ title">
Second-Level Title
<paragraph>
A paragraph.
(Note that the implicit hyperlink target generated by the "Second-Level Title" is preserved on the "subtitle" element itself.)
The following examples do not comply with the conditions:
More than one top-level section:
Top-Level Title =============== A paragraph. Another Top-Level Title ======================= Another paragraph.
The DocTitle transform will leave the document tree as-is. The document has no title. It is recommended to set the metadata title with the "title" directive.
More than one second-level section:
Top-Level Title =============== Second-Level Title ~~~~~~~~~~~~~~~~~~ A paragraph. Another Second-Level Title ~~~~~~~~~~~~~~~~~~~~~~~~~~ Another paragraph.
Step 2 is skipped. "Top-Level Title" becomes the document title; "Second-Level Title" and "Another Second-Level Title" become titles of top-level sections.
This is what you normally want in a document with title but no subtitle.
Body elements before the first section: [4]
.. note:: This element would not stop the transform, if it were nested in a header. Top-Level Title =============== A paragraph.
The DocTitle transform will leave the document tree as-is. The document has no title.
A configuration file entry "doctitle_xform: False" or converting with the CLI command
docutils --no-doc-title example.rst > example.html
The DocTitle transform is skipped. The document has no title.
standalone Reader
sectsubtitle_xform (default: False)
The SectSubTitle transform works like step 2 of the DocTitle transform, but for sections.
For example,
<section>
<title>
Title
<section>
<title>
Subtitle
...
is transformed into
<section>
<title>
Title
<subtitle>
Subtitle
...
This transform is disabled by default.
Appendix PreBibliographic ElementsThe document tree elements <comment>, <decoration>, <footer>, <header>, <meta>, <pending>, <raw>, <substitution_definition>, <subtitle>, <system_message>, <target>, and <title> are ignored when the DocTitle and DocInfo transforms check for elements before frontmatter candidates.
This means that in the reStructuredText source, comments, hyperlink targets, substitution definitions, and the directives "class", "default-role", "footer", "header", "meta", "raw", "sectnum", "sectnum", "target-notes", and "title" may be placed before the document title or bibliographic fields.
The DocTitle transform inserts document title and subtitle before these elements. DocInfo inserts the bibliographic fields before <comment>, <raw>, <substitution_definition>, and <target>.
For example, the document source:
.. a comment .. |today| date:: .. _hypertarget: http://example.org .. class:: spam .. role:: ham .. default-role:: ham .. footer:: footer text .. header:: header text .. meta:: :test: value .. raw:: html raw html text .. sectnum:: .. target-notes:: .. title:: metadata document title Top-Level Title =============== Second-Level Title ~~~~~~~~~~~~~~~~~~ :date: |today|
is parsed and transformed to:
<document ids="top-level-title" names="top-level\ title"
title="metadata document title">
<title>
Top-Level Title
<subtitle ids="second-level-title" names="second-level\ title">
Second-Level Title
<meta content="value" name="test">
<decoration>
<header>
<paragraph>
header text
<footer>
<paragraph>
footer text
<docinfo>
<date>
2024-03-01
<comment xml:space="preserve">
a comment
<substitution_definition names="today">
2024-03-01
<target ids="hypertarget" names="hypertarget" refuri="http://example.org">
<raw classes="spam" format="html" xml:space="preserve">
raw html text
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4