sphinx-autodoc-docutils

Alpha GitHub PyPI

Experimental Sphinx extension for documenting docutils directives and role callables as reference material. The extension does not invent a new domain; instead it introspects Python modules and renders copyable rst:directive and rst:role reference blocks from the live objects.

$ pip install sphinx-autodoc-docutils

Downstream conf.py

extensions = ["sphinx_autodoc_docutils"]

Working usage examples

Use a single-object directive when you want one rendered reference entry:

```{eval-rst}
.. autodirective:: my_project.docs_ext.MyDirective
```

```{eval-rst}
.. autorole:: my_project.docs_roles.cli_option_role
```

Use the bulk directives to render a full module reference plus an index:

```{eval-rst}
.. autodirective-index:: my_project.docs_ext
```

```{eval-rst}
.. autodirectives:: my_project.docs_ext
```

```{eval-rst}
.. autorole-index:: my_project.docs_roles
```

```{eval-rst}
.. autoroles:: my_project.docs_roles
```

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.

Index demo directives

Directive Index

Name	Python path	Summary
demobadge	docutils_demo.DemoBadgeDirective	Render a short badge-like paragraph for directive demos.
democallout	docutils_demo.DemoCalloutDirective	Render a simple titled container for directive demos.

Document one demo directive

.. demobadge::

Render a short badge-like paragraph for directive demos.

Python path: docutils_demo.DemoBadgeDirective

Required arguments: 1

Optional arguments: 0

Final argument whitespace: True

Has content: False

Options:

:class:

Validator: class_option.

Index demo roles

Role Index

Name	Python path	Summary
demo-badge	docutils_demo.demo_badge_role	Return a literal node with badge-style classes.

Document one demo role

:demo-badge:

Return a literal node with badge-style classes.

Python path: docutils_demo.demo_badge_role

Options:

• class: class_option

Accepts role content: True

Bulk directives demo

Renders all directive classes in a module at once:

.. demobadge::

Render a short badge-like paragraph for directive demos.

Python path: docutils_demo.DemoBadgeDirective

Required arguments: 1

Optional arguments: 0

Final argument whitespace: True

Has content: False

Options:

:class:

Validator: class_option.

.. democallout::

Render a simple titled container for directive demos.

Python path: docutils_demo.DemoCalloutDirective

Required arguments: 0

Optional arguments: 0

Final argument whitespace: False

Has content: True

Options:

:title:

Validator: unchanged_required.

Bulk roles demo

Renders all role callables in a module at once:

:demo-badge:

Return a literal node with badge-style classes.

Python path: docutils_demo.demo_badge_role

Options:

• class: class_option

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",
]

Package metadata

• Source on GitHub: sphinx-autodoc-docutils

• PyPI: sphinx-autodoc-docutils

• Maturity: Alpha

Registered Surface

sphinx_autodoc_docutils

Directives

Name	Kind	Callable	Summary
autodirective	directive	AutoDirective	Render documentation for a single directive class.
autodirectives	directive	AutoDirectives	Render documentation for every directive class in a module.
autodirective-index	directive	AutoDirectiveIndex	Generate a summary index for all directives in a module.
autorole	directive	AutoRole	Render documentation for a single role callable.
autoroles	directive	AutoRoles	Render documentation for every role callable in a module.
autorole-index	directive	AutoRoleIndex	Generate a summary index for all roles in a module.

autodirective options

Option
:no-index:	Registered option

autodirectives options

Option
:no-index:	Registered option

autorole options

Option
:no-index:	Registered option

autoroles options

Option
:no-index:	Registered option

Source on GitHub · PyPI