sphinx.util.nodes

module documentation

Docutils node-related utility functions for Sphinx.

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

Constant	`IGNORED_NODES`	Undocumented
Constant	`IMAGE_TYPE_NODES`	Undocumented
Constant	`LITERAL_TYPE_NODES`	Undocumented
Constant	`META_TYPE_NODES`	Undocumented
Constant	`NON_SMARTQUOTABLE_PARENT_NODES`	Undocumented
Variable	`explicit_title_re`	Undocumented
Variable	`indextypes`	Undocumented
Variable	`logger`	Undocumented
Class	`NodeMatcher`	A helper class for Node.findall().
Function	`_make_id`	Convert `string` into an identifier and return it.
Function	`_new_copy`	monkey-patch Element.copy to copy the rawsource and line for docutils-0.16 or older versions.
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_pending_meta`	Undocumented
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.
Variable	`_non_id_at_ends`	Undocumented
Variable	`_non_id_chars`	Undocumented
Variable	`_non_id_translate`	Undocumented
Variable	`_non_id_translate_digraphs`	Undocumented

IGNORED_NODES =

Undocumented

Value

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

IMAGE_TYPE_NODES =

Undocumented

Value

(nodes.image)

LITERAL_TYPE_NODES =

Undocumented

Value

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

META_TYPE_NODES =

Undocumented

Value

(addnodes.meta)

NON_SMARTQUOTABLE_PARENT_NODES =

Undocumented

Value

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

explicit_title_re =

Undocumented

indextypes: list[str] =

Undocumented

logger =

Undocumented

def _make_id(string):

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

def _new_copy(self):

monkey-patch Element.copy to copy the rawsource and line for docutils-0.16 or older versions.

refs: https://sourceforge.net/p/docutils/patches/165/

Returns
`Element`	Undocumented

def apply_source_workaround(node):

Undocumented

Parameters
node:`Element`	Undocumented

def clean_astext(node):

Like node.astext(), but ignore images.

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

def copy_source_info(src, dst):

Undocumented

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

def extract_messages(doctree):

Extract translatable messages from a document tree.

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

def find_pending_xref_condition(node, condition):

Pick matched pending_xref_condition node up from the pending_xref.

Parameters
node:`addnodes.pending_xref`	Undocumented
condition:`str`	Undocumented
Returns
`Optional[Element]`	Undocumented

def get_full_module_name(node):

Return full module dotted path like: 'docutils.nodes.paragraph'

Parameters
node:`Node`	Undocumented
nodes.Node node	target node
Returns
`str`	full module dotted path

def get_node_line(node):

Undocumented

Parameters
node:`Element`	Undocumented
Returns
`Optional[int]`	Undocumented

def get_node_source(node):

Undocumented

Parameters
node:`Element`	Undocumented
Returns
`Optional[str]`	Undocumented

def get_prev_node(node):

Undocumented

Parameters
node:`Node`	Undocumented
Returns
`Optional[Node]`	Undocumented

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

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_pending_meta(node):

Undocumented

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

def is_smartquotable(node):

Check whether the node is smart-quotable or not.

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

def is_translatable(node):

Undocumented

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

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

Generate an appropriate node_id for given prefix and term.

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

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

Shortcut to create a reference node.

Parameters
builder:`Builder`	Undocumented
fromdocname:`str`	Undocumented
todocname:`str`	Undocumented
targetid:`str`	Undocumented
child:`Union[Node, List[Node]]`	Undocumented
title:`str`	Undocumented
Returns
`nodes.reference`	Undocumented

def nested_parse_with_titles(state, content, node):

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

Undocumented

Parameters
entry:`str`	Undocumented
targetid:`str`	Undocumented
Returns
`List[Tuple[str, str, str, str, Optional[str]]]`	Undocumented

def process_only_nodes(document, tags):

Filter only nodes which do not match tags.

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

def repr_domxml(node, length=80):

return DOM XML representation of the specified node like: '<paragraph translatable="False"><inline classes="versionmodified">New in version...'

Parameters
node:`Node`	Undocumented
length:`int`	Undocumented
nodes.Node node	target node
int length	length of return value to be striped. if false-value is specified, repr_domxml returns full of DOM XML representation.
Returns
`str`	DOM XML representation

def set_role_source_info(inliner, lineno, node):

Undocumented

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

def set_source_info(directive, node):

Undocumented

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

def split_explicit_title(text):

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

Undocumented

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

def traverse_translatable_index(doctree):

Traverse translatable index node from a document tree.

Parameters
doctree:`Element`	Undocumented
Returns
`Iterable[Tuple[Element, List[IndexEntry]]]`	Undocumented

_non_id_at_ends =

Undocumented

_non_id_chars =

Undocumented

_non_id_translate: dict[int, str] =

Undocumented

_non_id_translate_digraphs: dict[int, str] =

Undocumented