Examples

Live demos

This page intentionally uses directive and role autodoc to document the documentation helpers themselves. If that feels a little recursive, that is the point: roles and directives should be documentable the same way fixtures are.

Document one demo directive

.. demobadge::

directive

directive

.. demobadge::

Render a short badge-like paragraph for directive demos.

Options:

Python path:

docutils_demo.DemoBadgeDirective

Required arguments:

1

Optional arguments:

0

Final argument whitespace:

True

Has content:

False

:class:

option

option

:class:

Validator: class_option.

Document one demo role

:demo-badge:

role

role

:demo-badge:

Return a literal node with badge-style classes.

Python path:

docutils_demo.demo_badge_role

Accepts role content:

True

class:

class_option

Bulk directives demo

Renders all directive classes in a module at once:

.. demobadge::

directive

directive

.. demobadge::

Render a short badge-like paragraph for directive demos.

Options:

Python path:

docutils_demo.DemoBadgeDirective

Required arguments:

1

Optional arguments:

0

Final argument whitespace:

True

Has content:

False

:class:

option

option

:class:

Validator: class_option.

.. democallout::

directive

directive

.. democallout::

Render a simple titled container for directive demos.

Options:

Python path:

docutils_demo.DemoCalloutDirective

Required arguments:

0

Optional arguments:

0

Final argument whitespace:

False

Has content:

True

:title:

option

option

:title:

Validator: unchanged_required.

Bulk roles demo

Renders all role callables in a module at once:

:demo-badge:

role

role

:demo-badge:

Return a literal node with badge-style classes.

Python path:

docutils_demo.demo_badge_role

Accepts role content:

True

class:

class_option

Document one demo transform

The single form imports the class directly and surfaces its default_priority and registration phase:

docutils_demo_components.DemoReorderTransform

transform priority 760

transform priority 760

docutils_demo_components.DemoReorderTransform

Move demo-badge paragraphs ahead of their sibling paragraphs.

Python path:

docutils_demo_components.DemoReorderTransform

Default priority:

760

Registered via:

app.add_transform()

Bulk transforms demo

Renders every transform a module registers via docutils_demo_components.setup() — here the demo module’s add_transform() call:

docutils_demo_components.DemoReorderTransform

transform priority 760

transform priority 760

docutils_demo_components.DemoReorderTransform

Move demo-badge paragraphs ahead of their sibling paragraphs.

Python path:

docutils_demo_components.DemoReorderTransform

Default priority:

760

Registered via:

app.add_transform()

Document one demo reader

Readers have no Sphinx registration call, so the single form imports the class and surfaces its formats, config section, and transform set:

docutils_demo_components.DemoArticleReader

reader

reader

docutils_demo_components.DemoArticleReader

Read standalone article sources with the demo transform applied.

Python path:

docutils_demo_components.DemoArticleReader

Supported formats:

demo-article

Config section:

demo article reader

Transforms:

Decorations, ExposeInternals, StripComments, Substitutions, PropagateTargets, DocTitle, SectionSubTitle, DocInfo, AnonymousHyperlinks, IndirectHyperlinks, Footnotes, ExternalTargets, InternalTargets, DanglingReferences, Transitions, DemoReorderTransform

Bulk readers demo

Renders every reader class a module defines:

docutils_demo_components.DemoArticleReader

reader

reader

docutils_demo_components.DemoArticleReader

Read standalone article sources with the demo transform applied.

Python path:

docutils_demo_components.DemoArticleReader

Supported formats:

demo-article

Config section:

demo article reader

Transforms:

Decorations, ExposeInternals, StripComments, Substitutions, PropagateTargets, DocTitle, SectionSubTitle, DocInfo, AnonymousHyperlinks, IndirectHyperlinks, Footnotes, ExternalTargets, InternalTargets, DanglingReferences, Transitions, DemoReorderTransform

Document one demo parser

Parsers surface their alias tuple and, when the module’s docutils_demo_components.setup() calls add_source_parser(), the Sphinx registration:

docutils_demo_components.DemoLineParser

parser

parser

docutils_demo_components.DemoLineParser

Parse line-oriented demo sources into one paragraph per line.

Python path:

docutils_demo_components.DemoLineParser

Supported aliases:

demo-lines, demolines

Config section:

demo line parser

Registered via:

app.add_source_parser()

Bulk parsers demo

docutils_demo_components.DemoLineParser

parser

parser

docutils_demo_components.DemoLineParser

Parse line-oriented demo sources into one paragraph per line.

Python path:

docutils_demo_components.DemoLineParser

Supported aliases:

demo-lines, demolines

Config section:

demo line parser

Registered via:

app.add_source_parser()

Document one demo writer

Writers surface their output formats and translator class — resolved defensively, since writers commonly assign translator_class inside __init__:

docutils_demo_components.DemoPlainWriter

writer

writer

docutils_demo_components.DemoPlainWriter

Write documents as plain text lines, one paragraph per line.

Python path:

docutils_demo_components.DemoPlainWriter

Supported formats:

demo-plain

Translator class:

docutils_demo_components.DemoTextTranslator

Config section:

demo plain writer

Transforms:

Messages, FilterMessages, StripClassesAndElements

Bulk writers demo

docutils_demo_components.DemoPlainWriter

writer

writer

docutils_demo_components.DemoPlainWriter

Write documents as plain text lines, one paragraph per line.

Python path:

docutils_demo_components.DemoPlainWriter

Supported formats:

demo-plain

Translator class:

docutils_demo_components.DemoTextTranslator

Config section:

demo plain writer

Transforms:

Messages, FilterMessages, StripClassesAndElements

Document one demo node

Custom node classes surface their base classes, docutils element categories, and the builders their visit/depart handlers were registered for via add_node():

docutils_demo_components.demo_marker

node

node

docutils_demo_components.demo_marker

Inline marker node rendered as a highlighted <mark> span.

Python path:

docutils_demo_components.demo_marker

Base classes:

General, Inline, Element

Categories:

Body, General, Inline

Visit/depart handlers:

html

Bulk nodes demo

docutils_demo_components.demo_marker

node

node

docutils_demo_components.demo_marker

Inline marker node rendered as a highlighted <mark> span.

Python path:

docutils_demo_components.demo_marker

Base classes:

General, Inline, Element

Categories:

Body, General, Inline

Visit/depart handlers:

html

Document one demo translator

Translators surface their base class, the visit/depart methods the class itself defines, and the builder the module’s docutils_demo_components.setup() registers them for via set_translator() — including an override badge:

docutils_demo_components.DemoTextTranslator

translator override

translator override

docutils_demo_components.DemoTextTranslator

Translate paragraphs into plain text lines for the demo writer.

Python path:

docutils_demo_components.DemoTextTranslator

Base class:

NodeVisitor

Overrides:

depart_paragraph, visit_Text, visit_paragraph

Registered for builder:

demo-plain

Bulk translators demo

docutils_demo_components.DemoTextTranslator

translator override

translator override

docutils_demo_components.DemoTextTranslator

Translate paragraphs into plain text lines for the demo writer.

Python path:

docutils_demo_components.DemoTextTranslator

Base class:

NodeVisitor

Overrides:

depart_paragraph, visit_Text, visit_paragraph

Registered for builder:

demo-plain

Cross-referencing components

Component entries register targets in the docutils domain, so prose can link to them: DemoReorderTransform resolves to the entry above, and docutils_demo_components.DemoReorderTransform spells out the full path. Every component type has a matching role — DemoArticleReader links the reader entry the same way.

The extension itself registers directives, not docutils roles or Sphinx config values. The generated package reference below lists its registered surface from the live docutils_demo_components.setup() calls.

Copyable config snippet

extensions = [
    "sphinx_autodoc_docutils",
]

Demo module reference

The demo objects above, as plain Python API — the targets the entries’ Python path facts link to:

Synthetic directives and roles for live autodoc-docutils demos.

Examples

>>> DemoBadgeDirective.required_arguments
1
>>> demo_badge_role.content
True

class docutils_demo.DemoBadgeDirective

class

class

class docutils_demo.DemoBadgeDirective

Bases: Directive

Render a short badge-like paragraph for directive demos.

required_arguments = 1

attribute

attribute

required_arguments = 1

Number of required directive arguments.

optional_arguments = 0

attribute

attribute

optional_arguments = 0

Number of optional arguments after the required arguments.

final_argument_whitespace = True

attribute

attribute

final_argument_whitespace = True

May the final argument contain whitespace?

has_content = False

attribute

attribute

has_content = False

May the directive have content?

option_spec: ClassVar[dict[str, Any]] = {'class': <function class_option>}

attribute

attribute

option_spec: ClassVar[dict[str, Any]] = {'class': <function class_option>}

Mapping of option names to validator functions.

run()

method

method

run()

Return a paragraph node for the requested badge label.

Return type:

list[Node]

class docutils_demo.DemoCalloutDirective

class

class

class docutils_demo.DemoCalloutDirective

Bases: Directive

Render a simple titled container for directive demos.

required_arguments = 0

attribute

attribute

required_arguments = 0

Number of required directive arguments.

optional_arguments = 0

attribute

attribute

optional_arguments = 0

Number of optional arguments after the required arguments.

has_content = True

attribute

attribute

has_content = True

May the directive have content?

option_spec: ClassVar[dict[str, Any]] = {'title': <function unchanged_required>}

attribute

attribute

option_spec: ClassVar[dict[str, Any]] = {'title': <function unchanged_required>}

Mapping of option names to validator functions.

run()

method

method

run()

Return a container with an optional title and paragraph content.

Return type:

list[Node]

docutils_demo.demo_badge_role(name, rawtext, text, lineno, inliner, options=None, content=None)

function

function

docutils_demo.demo_badge_role(name, rawtext, text, lineno, inliner, options=None, content=None)

Return a literal node with badge-style classes.

Examples

>>> nodes_, messages = demo_badge_role(
...     "demo-badge",
...     ":demo-badge:`Alpha`",
...     "Alpha",
...     1,
...     None,
... )
>>> nodes_[0].astext()
'Alpha'
>>> messages
[]

Parameters:

• name (str)

• rawtext (str)

• text (str)

• lineno (int)

• inliner (Inliner | None)

• options (dict[str, Any] | None)

• content (list[str] | None)

Return type:

tuple[list[Node], list[system_message]]

Synthetic docutils components for live component-autodoc demos.

Grows one demo class per component type so the docs/packages/sphinx-autodoc-docutils examples page can exercise every auto* directive against realistic metadata.

Examples

>>> DemoReorderTransform.default_priority
760

class docutils_demo_components.DemoReorderTransform

class

class

class docutils_demo_components.DemoReorderTransform

Bases: Transform

Move demo-badge paragraphs ahead of their sibling paragraphs.

Runs late in the read phase (priority 760) so it sees the fully parsed document but still precedes reference resolution.

default_priority = 760

attribute

attribute

default_priority = 760

Numerical priority of this transform, 0 through 999 (override).

apply()

method

method

apply()

Hoist each demo-badge paragraph to the front of its parent.

Return type:

None

class docutils_demo_components.DemoArticleReader

class

class

class docutils_demo_components.DemoArticleReader

Bases: Reader

Read standalone article sources with the demo transform applied.

Extends the stock standalone reader’s transform set with DemoReorderTransform so demo badges surface first.

supported = ('demo-article',)

attribute

attribute

supported = ('demo-article',)

Contexts this reader supports.

config_section = 'demo article reader'

attribute

attribute

config_section = 'demo article reader'

The name of the config file section specific to this component (lowercase, no brackets). Override in subclasses.

get_transforms()

method

method

get_transforms()

Return the standalone transforms plus the demo reorderer.

Return type:

list[type[Transform]]

class docutils_demo_components.DemoLineParser

class

class

class docutils_demo_components.DemoLineParser

Bases: Parser

Parse line-oriented demo sources into one paragraph per line.

supported = ('demo-lines', 'demolines')

attribute

attribute

supported = ('demo-lines', 'demolines')

Name and aliases for this component. Override in subclasses.

config_section = 'demo line parser'

attribute

attribute

config_section = 'demo line parser'

The name of the config file section specific to this component (lowercase, no brackets). Override in subclasses.

parse(inputstring, document)

method

method

parse(inputstring, document)

Append one paragraph node per non-empty input line.

Parameters:

• inputstring (str)

• document (document)

Return type:

None

class docutils_demo_components.demo_marker

class

class

class docutils_demo_components.demo_marker

Bases: General, Inline, Element

Inline marker node rendered as a highlighted <mark> span.

docutils_demo_components.visit_demo_marker(translator, node)

function

function

docutils_demo_components.visit_demo_marker(translator, node)

Open the <mark> wrapper for a demo marker node.

Parameters:

• translator (NodeVisitor)

• node (demo_marker)

Return type:

None

docutils_demo_components.depart_demo_marker(translator, node)

function

function

docutils_demo_components.depart_demo_marker(translator, node)

Close the <mark> wrapper for a demo marker node.

Parameters:

• translator (NodeVisitor)

• node (demo_marker)

Return type:

None

class docutils_demo_components.DemoTextTranslator

class

class

class docutils_demo_components.DemoTextTranslator

Bases: NodeVisitor

Translate paragraphs into plain text lines for the demo writer.

__init__(document)

method

method

__init__(document)

Parameters:

document (document)

Return type:

None

visit_paragraph(node)

method

method

visit_paragraph(node)

Open a fresh output line.

Parameters:

node (paragraph)

Return type:

None

depart_paragraph(node)

method

method

depart_paragraph(node)

Close the current output line.

Parameters:

node (paragraph)

Return type:

None

visit_Text(node)

method

method

visit_Text(node)

Append literal text to the current line.

Parameters:

node (Text)

Return type:

None

unknown_visit(node)

method

method

unknown_visit(node)

Ignore nodes the demo writer does not understand.

Parameters:

node (Node)

Return type:

None

unknown_departure(node)

method

method

unknown_departure(node)

Ignore nodes the demo writer does not understand.

Parameters:

node (Node)

Return type:

None

class docutils_demo_components.DemoPlainWriter

class

class

class docutils_demo_components.DemoPlainWriter

Bases: Writer

Write documents as plain text lines, one paragraph per line.

Assigns translator_class in __init__ (the django-docutils style) rather than as a class attribute, which exercises the defensive resolution the autowriter directive performs.

supported = ('demo-plain',)

attribute

attribute

supported = ('demo-plain',)

Name and aliases for this component. Override in subclasses.

config_section = 'demo plain writer'

attribute

attribute

config_section = 'demo plain writer'

The name of the config file section specific to this component (lowercase, no brackets). Override in subclasses.

__init__()

method

method

__init__()

Return type:

None

translate()

method

method

translate()

Visit the document and join the collected lines.

Return type:

None

docutils_demo_components.setup(app)

function

function

docutils_demo_components.setup(app)

Register the demo components with Sphinx.

Examples

>>> class FakeApp:
...     def __init__(self) -> None:
...         self.calls: list[tuple[str, object]] = []
...     def add_transform(self, cls: object) -> None:
...         self.calls.append(("add_transform", cls))
...     def add_source_parser(self, cls: object) -> None:
...         self.calls.append(("add_source_parser", cls))
...     def add_node(self, cls: object, **kwargs: object) -> None:
...         self.calls.append(("add_node", cls))
...     def set_translator(self, name: str, cls: object, **kwargs: object) -> None:
...         self.calls.append(("set_translator", cls))
>>> fake = FakeApp()
>>> metadata = setup(fake)  # type: ignore[arg-type]
>>> ("add_transform", DemoReorderTransform) in fake.calls
True
>>> ("add_source_parser", DemoLineParser) in fake.calls
True
>>> ("add_node", demo_marker) in fake.calls
True
>>> ("set_translator", DemoTextTranslator) in fake.calls
True
>>> metadata["parallel_read_safe"]
True

Parameters:

app (Sphinx)

Return type:

ExtensionMetadata