Docutils | Overview | About | Users | Reference | Developers

Docutils Transforms

Author:

David Goodger

Contact:
docutils-develop@lists.sourceforge.net
Revision:
$Revision$
Date:
$Date$
Copyright:
This document has been placed in the public domain.

Introduction

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.

There are transforms 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 about transforms and the Transformer object, see also PEP 258. (The default_transforms() attribute of component classes mentioned there is deprecated. Use the get_transforms() method instead.)

Transforms Listed in Priority Order

Transform 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

Writer (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

Reader (r)

740

peps.PEPZero

peps.Headers (t/p)

760

components.Filter

not used

780

universal.Decorations

Reader (r)

820

misc.Transitions

standalone (r), pep (r)

830

universal.Validate

Parser

835

universal.ExposeInternals

Reader (r)

840

references.DanglingReferences

standalone (r), pep (r)

850

universal.SmartQuotes

Parser

855

universal.Messages

Writer (w)

860

universal.FilterMessages

Writer (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:

Transform Priority Range Categories

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 components

readers.Reader:
universal.Decorations,
universal.ExposeInternals,
universal.StripComments
readers.ReReader:

None

readers.standalone.Reader:
references.Substitutions,
references.PropagateTargets,
frontmatter.DocTitle,
frontmatter.SectionSubTitle,
frontmatter.DocInfo,
references.AnonymousHyperlinks,
references.IndirectHyperlinks,
references.Footnotes,
references.ExternalTargets,
references.InternalTargets,
references.DanglingReferences,
misc.Transitions
readers.pep.Reader:
references.Substitutions,
references.PropagateTargets,
references.AnonymousHyperlinks,
references.IndirectHyperlinks,
references.Footnotes,
references.ExternalTargets,
references.InternalTargets,
references.DanglingReferences,
misc.Transitions,
peps.Headers,
peps.Contents,
peps.TargetNotes
parsers.rst.Parser

universal.SmartQuotes

writers.Writer:
universal.Messages,
universal.FilterMessages,
universal.StripClassesAndElements
writers.UnfilteredWriter

None

writers.latex2e.Writer

writer_aux.Admonitions

writers._html_base.Writer:

writer_aux.Admonitions

writers.odf_odt.Writer:

removes references.DanglingReferences

Transforms Reference

Incomplete. See also Transforms Listed in Priority Order and the sources in docutils/transforms.

DocInfo

Module:

frontmatter

Added by:

standalone Reader

Default priority:

340

Configuration setting:

docinfo_xform (default: True)

Given a document starting [1] 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

Module:

frontmatter

Added by:

standalone Reader

Default priority:

320

Configuration setting:

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.

  1. If the document contains a single top-level section as its first body element, [2] 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.

  2. 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, [2] 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.

Examples

The 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:

  1. 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.

  2. 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.

  3. Body elements before the first section: [2]

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

  4. 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.

SectSubTitle

Module:

frontmatter

Added by:

standalone Reader

Default priority:

350

Configuration setting:

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 Elements

The 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