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

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

Bases: docutils.parsers.rst.directives.admonitions.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][source]

Updates the title for the bloc itself.

source on GitHub

node_class[source]

alias of blocref_node

private_run(add_container=False)[source][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

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

Bases: docutils.parsers.rst.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

node_class[source]

alias of blocreflist

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

Bases: docutils.nodes.admonition

Defines blocref node.

source on GitHub

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

Bases: docutils.nodes.General, docutils.nodes.Element

defines blocreflist node

source on GitHub

pyquickhelper.sphinxext.sphinx_blocref_extension.depart_blocref_node(self, node)[source][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][source]

depart_blocref_node

source on GitHub

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

source on GitHub

pyquickhelper.sphinxext.sphinx_blocref_extension.process_blocref_nodes(app, doctree, fromdocname)[source][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][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][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][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]

source on GitHub

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

setup for blocref (sphinx)

source on GitHub

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

source on GitHub

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

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

source on GitHub