(api_lib_components)=

# Docutils components

Registry-aware reference for every docutils component django-docutils
ships, generated by
[sphinx-autodoc-docutils](https://gp-sphinx.git-pull.com/packages/sphinx-autodoc-docutils/).
Each entry surfaces the component's registry metadata — a transform's
`default_priority`, the writer's resolved translator class, a role's
content support — and registers a cross-reference target in the
`docutils` domain, so prose anywhere in these docs can link straight
to a component: {docutils:writer}`DjangoDocutilsWriter`,
{docutils:transform}`CodeTransform`.

django-docutils registers nothing with Sphinx itself (no builders,
domains, or config values) — it is a Django-side docutils consumer —
so the docutils component family below is the complete inventory.

## Writer

Full API: {ref}`api_lib_writers`.

```{eval-rst}
.. autowriter:: django_docutils.lib.writers.DjangoDocutilsWriter
```

## Translator

The translator's `Overrides` fact lists only the visit/depart handlers
the class defines itself — the customizations layered on docutils'
HTML5 translator.

Full API: {ref}`api_lib_writers`.

```{eval-rst}
.. autotranslator:: django_docutils.lib.writers.DjangoDocutilsHTMLTranslator
```

## Transforms

Full API: {ref}`api_lib_transforms_code`, {ref}`api_lib_transforms_toc`,
and {ref}`api_lib_sanitize`.

```{eval-rst}
.. autotransform:: django_docutils.lib.transforms.code.CodeTransform

.. autotransform:: django_docutils.lib.transforms.toc.Contents

.. autotransform:: django_docutils.lib.sanitize.SanitizeTransform
```

## Directives

Registered under the name configured in `DJANGO_DOCUTILS_LIB_RST`
(`code-block` by default, with `sourcecode` as a common alias) via
{func}`django_docutils.lib.directives.code.register_pygments_directive`. Full API: {ref}`api_lib_directives_code`.

```{eval-rst}
.. autodirective:: django_docutils.lib.directives.code.CodeBlock
```

## Roles

Role names shown here derive from the callable names; the names
actually registered with docutils come from the `roles` mapping in
`DJANGO_DOCUTILS_LIB_RST` (for example `gh` for {rst:role}`github`).
Full API: {ref}`api_lib_roles`.

```{eval-rst}
.. autorole:: django_docutils.lib.roles.email.email_role

.. autorole:: django_docutils.lib.roles.file.file_role

.. autorole:: django_docutils.lib.roles.file.manifest_role

.. autorole:: django_docutils.lib.roles.github.github_role

.. autorole:: django_docutils.lib.roles.hackernews.hackernews_role

.. autorole:: django_docutils.lib.roles.kbd.kbd_role

.. autorole:: django_docutils.lib.roles.leanpub.leanpub_role

.. autorole:: django_docutils.lib.roles.pypi.pypi_role

.. autorole:: django_docutils.lib.roles.readthedocs.readthedocs_role

.. autorole:: django_docutils.lib.roles.twitter.twitter_role

.. autorole:: django_docutils.lib.roles.url.url_role

.. autorole:: django_docutils.lib.roles.wikipedia.wikipedia_role
```