sphinx.util.docutils

module documentation

Utility functions for docutils.

Unknown Field: copyright
Copyright 2007-2022 by the Sphinx team, see AUTHORS.
Unknown Field: license
BSD, see LICENSE for details.

Class	`ReferenceRole`	A base class for reference roles.
Class	`SphinxDirective`	A base class for Sphinx directives.
Class	`SphinxRole`	A base class for Sphinx roles.
Variable	`__document_cache__`	Undocumented
Variable	`__version_info__`	Undocumented
Variable	`additional_nodes`	Undocumented
Variable	`logger`	Undocumented
Variable	`report_re`	Undocumented
Class	`CustomReSTDispatcher`	Custom reST's mark-up dispatcher.
Class	`ElementLookupError`	Undocumented
Class	`LoggingReporter`	No class docstring; 0/1 method, 1/1 class method documented
Class	`NullReporter`	A dummy reporter; write nothing.
Class	`sphinx_domains`	Monkey-patch directive and role dispatch, so that domain-specific markup takes precedence.
Class	`SphinxFileOutput`	Better FileOutput class for Sphinx.
Class	`SphinxTranslator`	A base class for Sphinx translators.
Class	`WarningStream`	Undocumented
Function	`docutils_namespace`	Create namespace for reST parsers.
Function	`findall`	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	`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.

__document_cache__: Optional[nodes.document] =

Undocumented

__version_info__ =

Undocumented

additional_nodes: Set[Type[Element]] =

Undocumented

logger =

Undocumented

report_re =

Undocumented

@contextmanager
def docutils_namespace():

Create namespace for reST parsers.

Returns
`Generator[None, None, None]`	Undocumented

def findall(self, *args, **kwargs):

Undocumented

def is_directive_registered(name):

Check the name directive is already registered.

Parameters
name:`str`	Undocumented
Returns
`bool`	Undocumented

def is_html5_writer_available():

Undocumented

Returns
`bool`	Undocumented

def is_node_registered(node):

Check the node is already registered.

Parameters
node:`Type[Element]`	Undocumented
Returns
`bool`	Undocumented

def is_role_registered(name):

Check the name role is already registered.

Parameters
name:`str`	Undocumented
Returns
`bool`	Undocumented

def new_document(source_path, settings=None):

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:`str`	Undocumented
settings:`Any`	Undocumented
Returns
`nodes.document`	Undocumented

@contextmanager
def patch_docutils(confdir=None):

Patch to docutils temporarily.

Parameters
confdir:`Optional[str]`	Undocumented
Returns
`Generator[None, None, None]`	Undocumented

@contextmanager
def patched_get_language():

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

def register_directive(name, directive):

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

Parameters
name:`str`	Undocumented
directive:`Type[Directive]`	Undocumented

def register_node(node):

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):

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

Parameters
name:`str`	Undocumented
role:`RoleFunction`	Undocumented

@contextmanager
def switch_source_input(state, content):

Switch current source input of state temporarily.

Parameters
state:`State`	Undocumented
content:`StringList`	Undocumented
Returns
`Generator[None, None, None]`	Undocumented

def unregister_node(node):

Unregister a node from docutils.

This is inverse of nodes._add_nodes_class_names().

Parameters
node:`Type[Element]`	Undocumented

def unregister_role(name):

Unregister a role from docutils.

Parameters
name:`str`	Undocumented

@contextmanager
def using_user_docutils_conf(confdir):

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

Parameters
confdir:`Optional[str]`	Undocumented
Returns
`Generator[None, None, None]`	Undocumented