lib.roles.registry

Register docutils roles for django-docutils.

django_docutils.lib.roles.registry.register_django_docutils_roles()

Register docutils roles for a django application.

Examples

In your site’s Django settings module:

>>> DJANGO_DOCUTILS_LIB_RST = {
...     #: directive-name: Directive class (import string)
...     'roles': {
...         'local': {  #: roles.register_local_role
...             # below: same as
...             # roles.register_local_role('gh', github_role)
...             'gh': 'django_docutils.lib.roles.github.git_role',
...             'pypi': 'django_docutils.lib.roles.pypi.pypi_role',
...         },
...         'canonical': {  #: roles.register_canonical_role
...             # below: same as:
...             # roles.register_canonical_role('class', PyXRefRole())
...             'class': 'django_docutils.lib.roles.xref.PyXRefRole',
...             # below: same as
...             # roles.register_canonical_role(
...             #     'ref',
...             #     XRefRole(
...             #         lowercase=True, innernodeclass=nodes.inline,
...             #         warn_dangling=True
...             #     )
...             # )
...             # See nodes.inline will be resolved
...             'ref': (
...                 'django_docutils.lib.roles.xref.XRefRole',
...                 {
...                     'lowercase': True,
...                     'innernodeclass': 'docutils.nodes.inline',
...                     'warn_dangling': True
...                 }
...             ),
...             'meth': (
...                 'django_docutils.lib.roles.xref.PyXRefRole',
...                 {
...                     'fix_parens': True,
...                 },
...             ),
...         },
...     },
... }
...

Return type:

None

django_docutils.lib.roles.registry.register_role_mapping(role_mapping)

Register a dict mapping of roles.

An item consists of a role name, import string to a callable, and an optional mapping of keyword args for special roles that are classes that can accept arguments.

The term inside ‘cb’ is short for callback/callable. Since the string can be any callable object: a function or class.

Parameters:

role_mapping (dict) – Mapping of docutils roles to register

Return type:

None