docutils.transforms.frontmatter.DocTitle Class Reference

Inheritance diagram for docutils.transforms.frontmatter.DocTitle:

Collaboration diagram for docutils.transforms.frontmatter.DocTitle:

Public Member Functions
	set_metadata (self)
	apply (self)
Public Member Functions inherited from docutils.transforms.frontmatter.TitlePromoter
	promote_title (self, node)
	promote_subtitle (self, node)
	candidate_index (self, node)
Public Member Functions inherited from docutils.transforms.Transform
	__init__ (self, document, startnode=None)

Public Attributes
	document
Public Attributes inherited from docutils.transforms.Transform
	document
	startnode
	language

Static Public Attributes
int	default_priority = 320
Static Public Attributes inherited from docutils.transforms.Transform
	default_priority = None

Detailed Description

In reStructuredText_, there is no way to specify a document title
and subtitle explicitly. Instead, we can supply the document title
(and possibly the subtitle as well) implicitly, and use this
two-step transform to "raise" or "promote" the title(s) (and their
corresponding section contents) to the document level.

1. If the document contains a single top-level section as its first
   element (instances of `nodes.PreBibliographic` are ignored),
   the top-level section's title becomes the document's title, and
   the top-level section's contents become the document's immediate
   contents. The title is also used for the <document> element's
   "title" attribute default value.

2. If step 1 successfully determines the document title, we
   continue by checking for a subtitle.

   If the lone top-level section itself contains a single second-level
   section as its first "non-PreBibliographic" element, that section's
   title is promoted to the document's subtitle, and that section's
   contents become the document's immediate contents.

Example:
   Given this input text::

       =================
        Top-Level Title
       =================

       Second-Level Title
       ~~~~~~~~~~~~~~~~~~

       A paragraph.

   After parsing and running the DocTitle transform, the result 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.)

Any `nodes.PreBibliographic` instances occurring before the
document title or subtitle are accumulated and inserted as
the first body elements after the title(s).

.. _reStructuredText: https://docutils.sourceforge.io/rst.html

Member Function Documentation

apply()

docutils.transforms.frontmatter.DocTitle.apply

(

self

)

Override to apply the transform to the document tree.

Reimplemented from docutils.transforms.Transform.

set_metadata()

docutils.transforms.frontmatter.DocTitle.set_metadata

(

self

)

Set document['title'] metadata title from the following
sources, listed in order of priority:

* Existing document['title'] attribute.
* "title" setting.
* Document title node (as promoted by promote_title).

---

The documentation for this class was generated from the following file:

• docs/help/help-venv/lib/python3.12/site-packages/docutils/transforms/frontmatter.py