sphinx.util.docutils

module documentation
(source)

Utility functions for docutils.

Class CustomReSTDispatcher Custom reST's mark-up dispatcher.
Class LoggingReporter No class docstring; 0/1 method, 1/1 class method documented
Class NullReporter A dummy reporter; write nothing.
Class ReferenceRole A base class for reference roles.
Class sphinx_domains Monkey-patch directive and role dispatch, so that domain-specific markup takes precedence.
Class SphinxDirective A base class for Sphinx directives.
Class SphinxFileOutput Better FileOutput class for Sphinx.
Class SphinxRole A base class for Sphinx roles.
Class SphinxTranslator A base class for Sphinx translators.
Class WarningStream Undocumented
Exception ElementLookupError Undocumented
Function docutils_namespace Create namespace for reST parsers.
Function du19_footnotes Undocumented
Function is_directive_registered Check the *name* directive is already registered.
Function is_html5_writer_available Undocumented
Function is_node_registered Check the *node* is already registered.
Function is_role_registered Check the *name* role is already registered.
Function new_document Return a new empty document object. This is an alternative of docutils'.
Function patch_docutils Patch to docutils temporarily.
Function patched_get_language Patch docutils.languages.get_language() temporarily.
Function patched_rst_get_language Patch docutils.parsers.rst.languages.get_language(). Starting from docutils 0.17, get_language() in ``rst.languages`` also has a reporter, which needs to be disabled temporarily.
Function register_directive Register a directive to docutils.
Function register_node Register a node to docutils.
Function register_role Register a role to docutils.
Function switch_source_input Switch current source input of state temporarily.
Function unregister_node Unregister a node from docutils.
Function unregister_role Unregister a role from docutils.
Function using_user_docutils_conf Let docutils know the location of ``docutils.conf`` for Sphinx.
Variable __document_cache__ Undocumented
Variable additional_nodes Undocumented
Variable logger Undocumented
Variable report_re Undocumented
@contextmanager
def docutils_namespace(): (source)

Create namespace for reST parsers.

Returns
Generator[None, None, None]Undocumented
@contextmanager
def du19_footnotes(): (source)

Undocumented

Returns
Generator[None, None, None]Undocumented
def is_directive_registered(name): (source)

Check the *name* directive is already registered.

Parameters
name:strUndocumented
Returns
boolUndocumented
def is_html5_writer_available(): (source)

Undocumented

Returns
boolUndocumented
def is_node_registered(node): (source)

Check the *node* is already registered.

Parameters
node:type[Element]Undocumented
Returns
boolUndocumented
def is_role_registered(name): (source)

Check the *name* role is already registered.

Parameters
name:strUndocumented
Returns
boolUndocumented
def new_document(source_path, settings=None): (source)

Return a new empty document object. This is an alternative of docutils'. This is a simple wrapper for ``docutils.utils.new_document()``. It caches the result of docutils' and use it on second call for instantiation. This makes an instantiation of document nodes much faster.

Parameters
source_path:strUndocumented
settings:AnyUndocumented
Returns
nodes.documentUndocumented
@contextmanager
def patch_docutils(confdir=None): (source)

Patch to docutils temporarily.

Parameters
confdir:str|NoneUndocumented
Returns
Generator[None, None, None]Undocumented
@contextmanager
def patched_get_language(): (source)

Patch docutils.languages.get_language() temporarily. This ignores the second argument ``reporter`` to suppress warnings. refs: https://github.com/sphinx-doc/sphinx/issues/3788

Returns
Generator[None, None, None]Undocumented
@contextmanager
def patched_rst_get_language(): (source)

Patch docutils.parsers.rst.languages.get_language(). Starting from docutils 0.17, get_language() in ``rst.languages`` also has a reporter, which needs to be disabled temporarily. This should also work for old versions of docutils, because reporter is none by default. refs: https://github.com/sphinx-doc/sphinx/issues/10179

Returns
Generator[None, None, None]Undocumented
def register_directive(name, directive): (source)

Register a directive to docutils. This modifies global state of docutils. So it is better to use this inside ``docutils_namespace()`` to prevent side-effects.

Parameters
name:strUndocumented
directive:type[Directive]Undocumented
def register_node(node): (source)

Register a node to docutils. This modifies global state of some visitors. So it is better to use this inside ``docutils_namespace()`` to prevent side-effects.

Parameters
node:type[Element]Undocumented
def register_role(name, role): (source)

Register a role to docutils. This modifies global state of docutils. So it is better to use this inside ``docutils_namespace()`` to prevent side-effects.

Parameters
name:strUndocumented
role:RoleFunctionUndocumented
@contextmanager
def switch_source_input(state, content): (source)

Switch current source input of state temporarily.

Parameters
state:StateUndocumented
content:StringListUndocumented
Returns
Generator[None, None, None]Undocumented
def unregister_node(node): (source)

Unregister a node from docutils. This is inverse of ``nodes._add_nodes_class_names()``.

Parameters
node:type[Element]Undocumented
def unregister_role(name): (source)

Unregister a role from docutils.

Parameters
name:strUndocumented
@contextmanager
def using_user_docutils_conf(confdir): (source)

Let docutils know the location of ``docutils.conf`` for Sphinx.

Parameters
confdir:str|NoneUndocumented
Returns
Generator[None, None, None]Undocumented
__document_cache__: tuple[Values, Reporter] = (source)

Undocumented

additional_nodes: set[type[Element]] = (source)

Undocumented

logger = (source)

Undocumented

report_re = (source)

Undocumented