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, …
Classes¶
class |
truncated documentation |
---|---|
A |
|
Defines |
|
A list of all blocref entries, for a specific tag. |
|
defines |
Functions¶
function |
truncated documentation |
---|---|
depart_blocref_node, see https://github.com/sphinx-doc/sphinx/blob/master/sphinx/writers/html.py |
|
depart_blocref_node |
|
merge_blocref |
|
process_blocref_nodes |
|
process_blocref_nodes and other kinds of nodes, If the configuration file specifies a variable |
|
collect all blocrefs in the environment this is not done in the directive itself because it some transformations … |
|
collect all blocrefs in the environment this is not done in the directive itself because it some transformations … |
|
purge_blocrefs |
|
setup for |
|
visit_blocref_node |
|
visit_blocreflist_node see https://github.com/sphinx-doc/sphinx/blob/master/sphinx/writers/html.py |
Properties¶
property |
truncated documentation |
---|---|
|
Return the document root node of the tree containing this Node. |
|
Return the document root node of the tree containing this Node. |
Methods¶
method |
truncated documentation |
---|---|
Updates the title for the bloc itself. |
|
Builds a node |
|
Builds a node |
|
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, …
- 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 optionsort
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 questionFaqRef
, a magic commandNbRef
, an exampleExRef
. It supports option index in most of the extensions so that the documentation can refer to it.- 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.
- 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
- run()[source]¶
Builds a node
blocref_node
.
- 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:
- 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.
- class pyquickhelper.sphinxext.sphinx_blocref_extension.blocref_node(rawsource='', *children, **attributes)[source]¶
Bases:
admonition
Defines
blocref
node.
- class pyquickhelper.sphinxext.sphinx_blocref_extension.blocreflist(rawsource='', *children, **attributes)[source]¶
Bases:
General
,Element
defines
blocreflist
node
- 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
- pyquickhelper.sphinxext.sphinx_blocref_extension.depart_blocreflist_node(self, node)[source]¶
depart_blocref_node
- pyquickhelper.sphinxext.sphinx_blocref_extension.process_blocref_nodes(app, doctree, fromdocname)[source]¶
- 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.
- 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
- 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
- pyquickhelper.sphinxext.sphinx_blocref_extension.visit_blocreflist_node(self, node)[source]¶
see https://github.com/sphinx-doc/sphinx/blob/master/sphinx/writers/html.py