Docutils Transforms (original) (raw)

David Goodger

Contact:

docutils-develop@lists.sourceforge.net

Revision:

10113

Date:

2025-04-29

Copyright:

This document has been placed in the public domain.

Contents

• Introduction
• Transforms Listed in Priority Order
  • Transform Priority Range Categories
• Transforms added by components
• Transforms Reference
  • DocInfo
  • DocTitle
  • SectSubTitle
• Appendix
  • PreBibliographic Elements

Introduction

Transforms change the document tree in-place, add to the tree, or prune it. Transforms resolve references and footnote numbers, processinterpreted 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 fromdocutils.Component like Readers, Parsers, Writers, Input, Output) overwrite the get_transforms() method of their base class. After the Reader has finished processing, the Publisher callsTransformer.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.

Key:

• (r): Reader
• (w): Writer
• (d): Directive
• (t): Transform
• (/p): Via a element

Transform Priority Range Categories

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

See also Transforms Listed in Priority Orderand 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 element (except for "dedication" and "abstract", which become elements after ).

For example, this document fragment: