sphinx_gallery.backreferences

Backreferences Generator.

Parses example file code in order to keep track of used functions.

Functions

sphinx_gallery.backreferences.identify_names(script_blocks: list[Block], ref_regex: str, global_variables: dict[str, Any] | None = None, node='') → dict[str, list[dict[str, Any]]]

Build a codeobj summary by identifying and resolving used names.

Parameters:

• script_blocks (list) – (label, content, line_number) List where each element is a tuple with the label (‘text’ or ‘code’), the corresponding content string of block and the leading line number.

• ref_regex (str) – Regex to find references to python objects.

• global_variables (Optional[Dict[str, Any]]) – Global variables for examples. Default=None

• node (ast.Module or str) – The parsed node. Default=””.

Returns:

example_code_obj – Dict with information about all code object references found in an example. Keys are the names as used in the example, values are lists of possible resolved objects with the following keys:

• code_obj[‘name’] : function or class name (str)

• code_obj[‘module’] : module name (str)

• code_obj[‘module_short’] : shortened module name (str)

• code_obj[‘is_class’] : whether object is class (bool)

• code_obj[‘is_explicit’]whether object is an explicit

  backreference (referred to by sphinx markup) (bool)

Return type:

dict[str, list[dict[str, Any]]]

Examples using sphinx_gallery.backreferences.identify_names

Identifying function names in a script

Identifying function names in a script

Classes

class sphinx_gallery.backreferences.Backreference(fname, src_dir, target_dir, intro, title)

fname

Alias for field number 0

intro

Alias for field number 3

src_dir

Alias for field number 1

target_dir

Alias for field number 2

title

Alias for field number 4

class sphinx_gallery.backreferences.NameFinder(global_variables: dict[str, Any] | None = None)

Finds the longest form of variable names and their imports in code.

Only retains names from imported modules.

get_mapping() → list[tuple[str, str, bool, bool, bool]]

Map names used in code, using AST nodes, to their fully qualified names.

Returns:

options – List of tuples, each tuple containing the following information about an accessed_name:

accessed name : str, fully qualified name : str if it is a class attribute (i.e., property or method) : bool if it is a class : bool if it is an explicit backreference : bool (always false here)

Return type:

List[Tuple[str]]

visit_Attribute(node) → None

Add attributes, including their prefix, to accessed_names.

visit_Import(node, prefix: str = '') → None

For ‘import’ add node names to imported_names.

visit_ImportFrom(node) → None

For ‘from import’ add node names to imported_names, incl module prefix.

visit_Name(node) → None

Add node id to accessed_names.