module sphinxext.sphinx_blocref_extension

Inheritance diagram of pyquickhelper.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)[source]

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)[source]

Updates the title for the bloc itself.

source on GitHub

final_argument_whitespace = False[source]

May the final argument contain whitespace?

has_content = True[source]

May the directive have content?

node_class[source]

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>}[source]

Mapping of option names to validator functions.

optional_arguments = 0[source]

Number of optional arguments after the required arguments.

private_run(add_container=False)[source]

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[source]

Number of required directive arguments.

run()[source]

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)[source]

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[source]

May the final argument contain whitespace?

has_content = False[source]

May the directive have content?

node_class[source]

alias of blocreflist

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

Mapping of option names to validator functions.

optional_arguments = 0[source]

Number of optional arguments after the required arguments.

required_arguments = 0[source]

Number of required directive arguments.

run()[source]

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)[source]

Bases: admonition

Defines blocref node.

source on GitHub

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

Bases: General, Element

defines blocreflist node

source on GitHub

pyquickhelper.sphinxext.sphinx_blocref_extension.depart_blocref_node(self, node)[source]

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)[source]

depart_blocref_node

source on GitHub

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

source on GitHub

pyquickhelper.sphinxext.sphinx_blocref_extension.process_blocref_nodes(app, doctree, fromdocname)[source]

source on GitHub

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

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)[source]

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)[source]

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]

source on GitHub

pyquickhelper.sphinxext.sphinx_blocref_extension.setup(app)[source]

setup for blocref (sphinx)

source on GitHub

pyquickhelper.sphinxext.sphinx_blocref_extension.visit_blocref_node(self, node)[source]

source on GitHub

pyquickhelper.sphinxext.sphinx_blocref_extension.visit_blocreflist_node(self, node)[source]

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

source on GitHub