module sphinxext.sphinx_blocref_extension

Short summary

module pyquickhelper.sphinxext.sphinx_blocref_extension

Defines a sphinx extension to keep track of blocs such as examples, FAQ, …

source on GitHub

Classes

class	truncated documentation
BlocRef	A blocref entry, displayed in the form of an admonition. It takes the following options:
blocref_node	Defines blocref node.
BlocRefList	A list of all blocref entries, for a specific tag.
blocreflist	defines blocreflist node

Functions

function	truncated documentation
depart_blocref_node	depart_blocref_node, see https://github.com/sphinx-doc/sphinx/blob/master/sphinx/writers/html.py
depart_blocreflist_node	depart_blocref_node
merge_blocref	merge_blocref
process_blocref_nodes	process_blocref_nodes
process_blocref_nodes_generic	process_blocref_nodes and other kinds of nodes, If the configuration file specifies a variable blocref_include_blocrefs …
process_blocrefs	collect all blocrefs in the environment this is not done in the directive itself because it some transformations …
process_blocrefs_generic	collect all blocrefs in the environment this is not done in the directive itself because it some transformations …
purge_blocrefs	purge_blocrefs
setup	setup for blocref (sphinx)
visit_blocref_node	visit_blocref_node
visit_blocreflist_node	visit_blocreflist_node see https://github.com/sphinx-doc/sphinx/blob/master/sphinx/writers/html.py

Properties

property	truncated documentation
document	Return the document node at the root of the tree containing this Node.
document	Return the document node at the root of the tree containing this Node.

Methods

method	truncated documentation
_update_title	Updates the title for the bloc itself.
private_run	Builds a node blocref_node.
run	Builds a node blocref_node.
run	Simply insert an empty blocreflist node which will be replaced later when process_blocref_nodes is called

Documentation

Defines a sphinx extension to keep track of blocs such as examples, FAQ, …

source on GitHub

class pyquickhelper.sphinxext.sphinx_blocref_extension.BlocRef(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: BaseAdmonition

A blocref entry, displayed in the form of an admonition. It takes the following options:

• title: a title for the bloc

• tag: a tag to have several categories of blocs

• lid or label: a label to refer to

• index: to add an entry to the index (comma separated)

Example:

.. blocref::
    :title: example of a blocref
    :tag: example
    :lid: id-you-can-choose

    An example of code::

        print("mignon")

Which renders as:

example of a blocref

An example of code:

print("mignon")

All blocs can be displayed in another page by using blocreflist:

.. blocreflist::
    :tag: dummy_example
    :sort: title

Only examples tagged as dummy_example will be inserted here. The option sort sorts items by title, number, file. You also link to it by typing :ref:'anchor <id-you-can-choose>' which gives something like link_to_blocref. The link must receive a name.

example of a blocref

An example of code:

print("mignon")

(original entry : sphinx_blocref_extension.py:docstring of pyquickhelper.sphinxext.sphinx_blocref_extension.BlocRef, line 22)

This directive is used to highlight a bloc about anything BlocRef, a question FaqRef, a magic command NbRef, an example ExRef. It supports option index in most of the extensions so that the documentation can refer to it.

source on GitHub

_update_title(title, tag, lid)

Updates the title for the bloc itself.

source on GitHub

final_argument_whitespace = False

May the final argument contain whitespace?

has_content = True

May the directive have content?

node_class

alias of blocref_node

option_spec = {'class': <function class_option>, 'index': <function unchanged>, 'label': <function unchanged>, 'lid': <function unchanged>, 'tag': <function unchanged>, 'title': <function unchanged>}

Mapping of option names to validator functions.

optional_arguments = 0

Number of optional arguments after the required arguments.

private_run(add_container=False)

Builds a node blocref_node.

Parameters

add_container – add a container node and return as a second result

Returns

list of nodes or list of nodes, container

source on GitHub

required_arguments = 0

Number of required directive arguments.

run()

Builds a node blocref_node.

source on GitHub

class pyquickhelper.sphinxext.sphinx_blocref_extension.BlocRefList(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: Directive

A list of all blocref entries, for a specific tag.

• tag: a tag to filter bloc having this tag

• sort: a way to sort the blocs based on the title, file, number, default: title

• contents: add a bullet list with links to added blocs

Example:

.. blocreflist::
    :tag: issue
    :contents:

source on GitHub

final_argument_whitespace = False

May the final argument contain whitespace?

has_content = False

May the directive have content?

node_class

alias of blocreflist

option_spec = {'contents': <function unchanged>, 'sort': <function unchanged>, 'tag': <function unchanged>}

Mapping of option names to validator functions.

optional_arguments = 0

Number of optional arguments after the required arguments.

required_arguments = 0

Number of required directive arguments.

run()

Simply insert an empty blocreflist node which will be replaced later when process_blocref_nodes is called

source on GitHub

class pyquickhelper.sphinxext.sphinx_blocref_extension.blocref_node(rawsource='', *children, **attributes)

Bases: admonition

Defines blocref node.

source on GitHub

class pyquickhelper.sphinxext.sphinx_blocref_extension.blocreflist(rawsource='', *children, **attributes)

Bases: General, Element

defines blocreflist node

source on GitHub

pyquickhelper.sphinxext.sphinx_blocref_extension.depart_blocref_node(self, node)

depart_blocref_node, see https://github.com/sphinx-doc/sphinx/blob/master/sphinx/writers/html.py

source on GitHub

pyquickhelper.sphinxext.sphinx_blocref_extension.depart_blocreflist_node(self, node)

depart_blocref_node

source on GitHub

pyquickhelper.sphinxext.sphinx_blocref_extension.merge_blocref(app, env, docnames, other)

source on GitHub

pyquickhelper.sphinxext.sphinx_blocref_extension.process_blocref_nodes(app, doctree, fromdocname)

source on GitHub

pyquickhelper.sphinxext.sphinx_blocref_extension.process_blocref_nodes_generic(app, doctree, fromdocname, class_name, entry_name, class_node, class_node_list)

process_blocref_nodes and other kinds of nodes,

If the configuration file specifies a variable blocref_include_blocrefs equals to False, all nodes are removed.

source on GitHub

pyquickhelper.sphinxext.sphinx_blocref_extension.process_blocrefs(app, doctree)

collect all blocrefs in the environment this is not done in the directive itself because it some transformations must have already been run, e.g. substitutions

source on GitHub

pyquickhelper.sphinxext.sphinx_blocref_extension.process_blocrefs_generic(app, doctree, bloc_name, class_node)

collect all blocrefs in the environment this is not done in the directive itself because it some transformations must have already been run, e.g. substitutions

source on GitHub

pyquickhelper.sphinxext.sphinx_blocref_extension.purge_blocrefs(app, env, docname)

source on GitHub

pyquickhelper.sphinxext.sphinx_blocref_extension.setup(app)

setup for blocref (sphinx)

source on GitHub

pyquickhelper.sphinxext.sphinx_blocref_extension.visit_blocref_node(self, node)

source on GitHub

pyquickhelper.sphinxext.sphinx_blocref_extension.visit_blocreflist_node(self, node)

see https://github.com/sphinx-doc/sphinx/blob/master/sphinx/writers/html.py

source on GitHub