sphinx.util.nodes

module documentation

(source)

Docutils node-related utility functions for Sphinx.

Class	`NodeMatcher`	A helper class for Node.findall().
Function	`apply_source_workaround`	Undocumented
Function	`clean_astext`	Like node.astext(), but ignore images.
Function	`copy_source_info`	Undocumented
Function	`extract_messages`	Extract translatable messages from a document tree.
Function	`find_pending_xref_condition`	Pick matched pending_xref_condition node up from the pending_xref.
Function	`get_full_module_name`	Return full module dotted path like: 'docutils.nodes.paragraph'
Function	`get_node_line`	Undocumented
Function	`get_node_source`	Undocumented
Function	`get_prev_node`	Undocumented
Function	`inline_all_toctrees`	Inline all toctrees in the tree.
Function	`is_smartquotable`	Check whether the node is smart-quotable or not.
Function	`is_translatable`	Undocumented
Function	`make_id`	Generate an appropriate node_id for given prefix and term.
Function	`make_refnode`	Shortcut to create a reference node.
Function	`nested_parse_with_titles`	Version of state.nested_parse() that allows titles and does not require titles to have the same decoration as the calling document.
Function	`process_index_entry`	Undocumented
Function	`process_only_nodes`	Filter ``only`` nodes which do not match tags.
Function	`repr_domxml`	return DOM XML representation of the specified node like: '<paragraph translatable="False"><inline classes="versionmodified">New in version...'
Function	`set_role_source_info`	Undocumented
Function	`set_source_info`	Undocumented
Function	`split_explicit_title`	Split role content into title and target, if given.
Function	`traverse_parent`	Undocumented
Function	`traverse_translatable_index`	Traverse translatable index node from a document tree.
Constant	`IGNORED_NODES`	Undocumented
Constant	`IMAGE_TYPE_NODES`	Undocumented
Constant	`LITERAL_TYPE_NODES`	Undocumented
Constant	`NON_SMARTQUOTABLE_PARENT_NODES`	Undocumented
Variable	`explicit_title_re`	Undocumented
Variable	`indextypes`	Undocumented
Variable	`logger`	Undocumented
Function	`_copy_except__document`	Monkey-patch ```nodes.Element.copy``` to not copy the ``_document`` attribute.
Function	`_make_id`	Convert `string` into an identifier and return it.
Variable	`_non_id_at_ends`	Undocumented
Variable	`_non_id_chars`	Undocumented
Variable	`_non_id_translate`	Undocumented
Variable	`_non_id_translate_digraphs`	Undocumented

def apply_source_workaround(node): (source) ¶

Undocumented

Parameters
node:`Element`	Undocumented

def clean_astext(node): (source) ¶

Like node.astext(), but ignore images.

Parameters
node:`Element`	Undocumented
Returns
`str`	Undocumented

def copy_source_info(src, dst): (source) ¶

Undocumented

Parameters
src:`Element`	Undocumented
dst:`Element`	Undocumented

def extract_messages(doctree): (source) ¶

Extract translatable messages from a document tree.

Parameters
doctree:`Element`	Undocumented
Returns
`Iterable[tuple[Element, str]]`	Undocumented

def find_pending_xref_condition(node, condition): (source) ¶

Pick matched pending_xref_condition node up from the pending_xref.

Parameters
node:`addnodes.pending_xref`	Undocumented
condition:`str`	Undocumented
Returns
`Element\|None`	Undocumented

def get_full_module_name(node): (source) ¶

Return full module dotted path like: 'docutils.nodes.paragraph' :param nodes.Node node: target node :return: full module dotted path

Parameters
node:`Node`	Undocumented
Returns
`str`	Undocumented

def get_node_line(node): (source) ¶

Undocumented

Parameters
node:`Element`	Undocumented
Returns
`int`	Undocumented

def get_node_source(node): (source) ¶

Undocumented

Parameters
node:`Element`	Undocumented
Returns
`str`	Undocumented

def get_prev_node(node): (source) ¶

Undocumented

Parameters
node:`Node`	Undocumented
Returns
`Node\|None`	Undocumented

def inline_all_toctrees(builder, docnameset, docname, tree, colorfunc, traversed): (source) ¶

Inline all toctrees in the *tree*. Record all docnames in *docnameset*, and output docnames with *colorfunc*.

Parameters
builder:`Builder`	Undocumented
docnameset:`set[str]`	Undocumented
docname:`str`	Undocumented
tree:`nodes.document`	Undocumented
colorfunc:`Callable`	Undocumented
traversed:`list[str]`	Undocumented
Returns
`nodes.document`	Undocumented

def is_smartquotable(node): (source) ¶

Check whether the node is smart-quotable or not.

Parameters
node:`Node`	Undocumented
Returns
`bool`	Undocumented

def is_translatable(node): (source) ¶

Undocumented

Parameters
node:`Node`	Undocumented
Returns
`bool`	Undocumented

def make_id(env, document, prefix='', term=None): (source) ¶

Generate an appropriate node_id for given *prefix* and *term*.

Parameters
env:`BuildEnvironment`	Undocumented
document:`nodes.document`	Undocumented
prefix:`str`	Undocumented
term:`str\|None`	Undocumented
Returns
`str`	Undocumented

def make_refnode(builder, fromdocname, todocname, targetid, child, title=None): (source) ¶

Shortcut to create a reference node.

Parameters
builder:`Builder`	Undocumented
fromdocname:`str`	Undocumented
todocname:`str`	Undocumented
targetid:`str\|None`	Undocumented
child:`Node\|list[Node]`	Undocumented
title:`str\|None`	Undocumented
Returns
`nodes.reference`	Undocumented

def nested_parse_with_titles(state, content, node): (source) ¶

Version of state.nested_parse() that allows titles and does not require titles to have the same decoration as the calling document. This is useful when the parsed content comes from a completely different context, such as docstrings.

Parameters
state:`Any`	Undocumented
content:`StringList`	Undocumented
node:`Node`	Undocumented
Returns
`str`	Undocumented

def process_index_entry(entry, targetid): (source) ¶

Undocumented

Parameters
entry:`str`	Undocumented
targetid:`str`	Undocumented
Returns
`list[tuple[str, str, str, str, str\|None]]`	Undocumented

def process_only_nodes(document, tags): (source) ¶

Filter ``only`` nodes which do not match *tags*.

Parameters
document:`Node`	Undocumented
tags:`Tags`	Undocumented

def repr_domxml(node, length=80): (source) ¶

return DOM XML representation of the specified node like: '<paragraph translatable="False"><inline classes="versionmodified">New in version...' :param nodes.Node node: target node :param int length: length of return value to be striped. if false-value is specified, repr_domxml returns full of DOM XML representation. :return: DOM XML representation

Parameters
node:`Node`	Undocumented
length:`int`	Undocumented
Returns
`str`	Undocumented

def set_role_source_info(inliner, lineno, node): (source) ¶

Undocumented

Parameters
inliner:`Inliner`	Undocumented
lineno:`int`	Undocumented
node:`Node`	Undocumented

def set_source_info(directive, node): (source) ¶

Undocumented

Parameters
directive:`Directive`	Undocumented
node:`Node`	Undocumented

def split_explicit_title(text): (source) ¶

Split role content into title and target, if given.

Parameters
text:`str`	Undocumented
Returns
`tuple[bool, str, str]`	Undocumented

def traverse_parent(node, cls=None): (source) ¶

Undocumented

Parameters
node:`Element`	Undocumented
cls:`Any`	Undocumented
Returns
`Iterable[Element]`	Undocumented

def traverse_translatable_index(doctree): (source) ¶

Traverse translatable index node from a document tree.

Parameters
doctree:`Element`	Undocumented
Returns
`Iterable[tuple[Element, list[IndexEntry]]]`	Undocumented

IGNORED_NODES = (source) ¶

Undocumented

Value

(nodes.Invisible,
 nodes.literal_block,
 nodes.doctest_block,
 addnodes.versionmodified)

IMAGE_TYPE_NODES = (source) ¶

Undocumented

Value

(nodes.image)

LITERAL_TYPE_NODES = (source) ¶

Undocumented

Value

(nodes.literal_block, nodes.doctest_block, nodes.math_block, nodes.raw)

NON_SMARTQUOTABLE_PARENT_NODES = (source) ¶

Undocumented

Value

(nodes.FixedTextElement,
 nodes.literal,
 nodes.math,
 nodes.image,
 nodes.raw,
 nodes.problematic,
 addnodes.not_smartquotable)

explicit_title_re = (source) ¶

Undocumented

indextypes: list[str] = (source) ¶

Undocumented

logger = (source) ¶

Undocumented

def _copy_except__document(self): (source) ¶

Monkey-patch ```nodes.Element.copy``` to not copy the ``_document`` attribute. xref: https://github.com/sphinx-doc/sphinx/issues/11116#issuecomment-1376767086

Parameters
self:`Element`	Undocumented
Returns
`Element`	Undocumented

def _make_id(string): (source) ¶

Convert `string` into an identifier and return it. This function is a modified version of ``docutils.nodes.make_id()`` of docutils-0.16. Changes: * Allow to use capital alphabet characters * Allow to use dots (".") and underscores ("_") for an identifier without a leading character. # Author: David Goodger <goodger@python.org> # Maintainer: docutils-develop@lists.sourceforge.net # Copyright: This module has been placed in the public domain.

Parameters
string:`str`	Undocumented
Returns
`str`	Undocumented

_non_id_at_ends = (source) ¶

Undocumented

_non_id_chars = (source) ¶

Undocumented

_non_id_translate: dict[int, str] = (source) ¶

Undocumented

_non_id_translate_digraphs: dict[int, str] = (source) ¶

Undocumented