Examples

Live demos

This page also uses sphinx-autodoc-docutils to document the config-doc directives themselves, so the page demonstrates both config-value output and directive documentation.

Render a single demo config value

demo_debug

config env

config env

demo_debug

Type:

bool

Default:

False

Registered by:

sphinx_config_single_demo.setup()

Bulk config values demo

Renders all config values from a module at once:

demo_theme_accent

config html

config html

demo_theme_accent

Type:

dict

Default:

{'dark': 'teal', 'light': 'mint'}

Registered by:

sphinx_config_demo.setup()

demo_show_callouts

config html

config html

demo_show_callouts

Type:

bool

Default:

True

Registered by:

sphinx_config_demo.setup()

Document one demo builder

Builders surface their CLI name, output format, supported image types, and parallel-safety:

sphinx_demo_builder.DemoArchiveBuilder

builder archive

builder archive

sphinx_demo_builder.DemoArchiveBuilder

Bundle every rendered page into one archive artifact.

Python path:

sphinx_demo_builder.DemoArchiveBuilder

Builder name:

demo-archive

Output format:

archive

Supported image types:

image/svg+xml, image/png

Default translator:

—

Parallel-safe:

False

Epilog:

The demo archive is in %(outdir)s.

Bulk builders demo

Renders every builder a module registers via sphinx_demo_builder.setup():

sphinx_demo_builder.DemoArchiveBuilder

builder archive

builder archive

sphinx_demo_builder.DemoArchiveBuilder

Bundle every rendered page into one archive artifact.

Python path:

sphinx_demo_builder.DemoArchiveBuilder

Builder name:

demo-archive

Output format:

archive

Supported image types:

image/svg+xml, image/png

Default translator:

—

Parallel-safe:

False

Epilog:

The demo archive is in %(outdir)s.

Document one demo domain

Domains surface their registered name, label, object types, roles, and indices:

sphinx_demo_builder.DemoTopicDomain

domain demotopic

domain demotopic

sphinx_demo_builder.DemoTopicDomain

Describe demo topics with one object type and matching role.

Python path:

sphinx_demo_builder.DemoTopicDomain

Domain name:

demotopic

Label:

Demo topics

Object types:

topic

Roles:

topic

Directives:

—

Indices:

—

Bulk domains demo

The bulk form replays a package’s sphinx_autodoc_docutils.setup() — here documenting the docutils domain that sphinx-autodoc-docutils itself registers:

sphinx_autodoc_docutils.domain.DocutilsDomain

domain docutils

domain docutils

sphinx_autodoc_docutils.domain.DocutilsDomain

Sphinx domain for docutils component documentation.

Python path:

sphinx_autodoc_docutils.domain.DocutilsDomain

Domain name:

docutils

Label:

Docutils

Object types:

node, parser, reader, transform, translator, writer

Roles:

node, parser, reader, transform, translator, writer

Directives:

node, parser, reader, transform, translator, writer

Indices:

componentindex

Cross-referencing components

Component entries register targets in the sphinxext domain, so prose can link to them: DemoArchiveBuilder and DemoTopicDomain resolve to the entries above.

Demo module reference

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

Synthetic config registrations for live autodoc-sphinx demos.

Examples

>>> stub = type("App", (), {"add_config_value": lambda *a, **kw: None})()
>>> metadata = setup(stub)
>>> metadata["parallel_read_safe"]
True

sphinx_config_demo.setup(app)

function

function

sphinx_config_demo.setup(app)

Register a small config surface for documentation demos.

Parameters:

app (Any)

Return type:

dict[str, object]

Single-value config registration for the autoconfigvalue demo.

Examples

>>> stub = type("App", (), {"add_config_value": lambda *a, **kw: None})()
>>> metadata = setup(stub)
>>> metadata["parallel_write_safe"]
True

sphinx_config_single_demo.setup(app)

function

function

sphinx_config_single_demo.setup(app)

Register one config value for single-entry rendering demos.

Parameters:

app (Any)

Return type:

dict[str, object]

Synthetic Sphinx extension components for live autodoc demos.

Grows one demo class per component type so the docs/packages/sphinx-autodoc-sphinx examples page can exercise the autobuilder and autodomain directives against realistic metadata.

Examples

>>> DemoArchiveBuilder.name
'demo-archive'

class sphinx_demo_builder.DemoArchiveBuilder

class

class

class sphinx_demo_builder.DemoArchiveBuilder

Bases: Builder

Bundle every rendered page into one archive artifact.

A deliberately small builder: it reports all documents as outdated, writes nothing per page, and exists so the autodoc output has a realistic name/format/image-type surface to display.

name: str = 'demo-archive'

attribute

attribute

name: str = 'demo-archive'

The builder’s name. This is the value used to select builders on the command line.

format: str = 'archive'

attribute

attribute

format: str = 'archive'

The builder’s output format, or ‘’ if no document output is produced. This is commonly the file extension, e.g. “html”, though any string value is accepted. The builder’s format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

epilog: str = 'The demo archive is in %(outdir)s.'

attribute

attribute

epilog: str = 'The demo archive is in %(outdir)s.'

The message emitted upon successful build completion. This can be a printf-style template string with the following keys: outdir, project

supported_image_types: list[str] = ['image/svg+xml', 'image/png']

attribute

attribute

supported_image_types: list[str] = ['image/svg+xml', 'image/png']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

get_outdated_docs()

method

method

get_outdated_docs()

Report every document as outdated.

Return type:

Iterator[str]

get_target_uri(docname, typ=None)

method

method

get_target_uri(docname, typ=None)

Return the in-archive URI for a document.

Parameters:

• docname (str)

• typ (str | None)

Return type:

str

prepare_writing(docnames)

method

method

prepare_writing(docnames)

No writer state is needed for the demo.

Parameters:

docnames (Set[str])

Return type:

None

write_doc(docname, doctree)

method

method

write_doc(docname, doctree)

Skip per-document output; the demo archives nothing.

Parameters:

• docname (str)

• doctree (document)

Return type:

None

class sphinx_demo_builder.DemoTopicDomain

class

class

class sphinx_demo_builder.DemoTopicDomain

Bases: Domain

Describe demo topics with one object type and matching role.

name = 'demotopic'

attribute

attribute

name = 'demotopic'

domain name: should be short, but unique

label = 'Demo topics'

attribute

attribute

label = 'Demo topics'

domain label: longer, more descriptive (used in messages)

object_types: dict[str, ObjType] = {'topic': <sphinx.domains.ObjType object>}

attribute

attribute

object_types: dict[str, ObjType] = {'topic': <sphinx.domains.ObjType object>}

type (usually directive) name -> ObjType instance

roles: dict[str, RoleFunction | XRefRole] = {'topic': <sphinx.roles.XRefRole object>}

attribute

attribute

roles: dict[str, RoleFunction | XRefRole] = {'topic': <sphinx.roles.XRefRole object>}

role name -> role callable

sphinx_demo_builder.setup(app)

function

function

sphinx_demo_builder.setup(app)

Register the demo extension components with Sphinx.

Examples

>>> class FakeApp:
...     def __init__(self) -> None:
...         self.calls: list[tuple[str, object]] = []
...     def add_builder(self, cls: object) -> None:
...         self.calls.append(("add_builder", cls))
...     def add_domain(self, cls: object) -> None:
...         self.calls.append(("add_domain", cls))
>>> fake = FakeApp()
>>> metadata = setup(fake)  # type: ignore[arg-type]
>>> ("add_builder", DemoArchiveBuilder) in fake.calls
True
>>> ("add_domain", DemoTopicDomain) in fake.calls
True
>>> metadata["parallel_read_safe"]
True

Parameters:

app (Sphinx)

Return type:

ExtensionMetadata