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::.. 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
Document one demo role¶
-
:demo-badge::demo-badge:
Return a literal node with badge-style classes.
- Python path:
docutils_demo.demo_badge_role- Accepts role content:
True
Bulk directives demo¶
Renders all directive classes in a module at once:
-
.. demobadge::.. 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
-
.. democallout::.. 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
Bulk roles demo¶
Renders all role callables in a module at once:
-
:demo-badge::demo-badge:
Return a literal node with badge-style classes.
- Python path:
docutils_demo.demo_badge_role- Accepts role content:
True
The extension itself registers directives, not docutils roles or Sphinx config
values. The generated package reference below lists its registered surface from
the live setup() calls.
Copyable config snippet
extensions = [
"sphinx_autodoc_docutils",
]