blocref, exref, mathdef¶

They pretty much follows the same design. They highlight a paragraph and this paragraph can be recalled anywhere on another page. Some options differs depending on the content.

exref¶

Location: ExRef.

In conf.py:

extensions = [ ...
    'sphinx_runpython.blocdefs.sphinx_exref_extension']

exref_include_exrefs = True

An example:

.. exref::
    :title: How to add an example?
    :tag: example
    :label: l-this-example

    This example, a piece of code...

Which gives:

How to add an example?

This example, a piece of code…

A reference can be added to this example Example 1. The title needs to be recalled.

faqref¶

Location: FaqRef.

In conf.py:

extensions = [ ...
    'sphinx_runpython.blocdefs.sphinx_faqref_extension']

faqref_include_faqrefs = True

An example:

.. faqref::
    :title: How to add an example?
    :tag: faq1
    :label: l-this-faq

    This example, a piece of code...

Which gives:

How to add an example?

This example, a piece of code…

A reference can be added to this example Faq 1. The title needs to be recalled.

blocref¶

Location: BlocRef.

In conf.py:

extensions = [ ...
    'sphinx_runpython.blocdefs.sphinx_blocref_extension']

blocref_include_blocrefs = True

An example:

.. blocref::
    :title: How to add a bloc?
    :tag: bloc
    :label: l-this-bloc

    A bloc...

Which gives:

How to add a bloc?

A bloc…

A reference can be added to this bloc Bloc A. The title needs to be recalled.

mathdef¶

Location: MathDef.

In conf.py:

extensions = [ ...
    'sphinx_runpython.blocdefs.sphinx_mathdef_extension']

mathdef_include_mathdefs = True

An example:

.. mathdef::
    :title: How to add a definition?
    :tag: definition
    :label: l-this-def

    A definition...

Which gives:

definition D1 : How to add a definition?

A definition…

A reference can be added to this definition Def 1. The title needs to be recalled.

Directives¶

class sphinx_runpython.blocdefs.sphinx_blocref_extension.BlocRef(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶

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 sphinx_runpython.blocdefs.sphinx_blocref_extension.BlocRef, line 22)

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

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

Builds a node @see cl blocref_node.

Parameters:: add_container – add a container node and return as a second result
Returns:: list of nodes or list of nodes, container

required_arguments = 0¶: Number of required directive arguments.

run()[source]¶: Builds a node @see cl blocref_node.

class sphinx_runpython.blocdefs.sphinx_exref_extension.ExRef(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶

A exref 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 (optional)
lid or label: a label to refer to
index: to add an entry to the index (comma separated)

Example:

.. exref::
    :title: example of a blocref
    :label: id-you-can-choose7

    An example of code:

    ::

        print("mignon")

Which renders as:

example of a exref

An example of code:

print("mignon")

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

.. exreflist::
    :tag: dummy_example6
    :sort: title

Only blocs 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-choose7>' which gives something like link_to_blocref. The link must receive a name.

example of a exref

An example of code:

print("mignon")

(original entry : sphinx_exref_extension.py:docstring of sphinx_runpython.blocdefs.sphinx_exref_extension.ExRef, line 23)

node_class¶: alias of exref_node

run()[source]¶: Calls run from @see cl BlocRef and add defaut tag.

class sphinx_runpython.blocdefs.sphinx_faqref_extension.FaqRef(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶

A faqref 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 (optional)
lid or label: a label to refer to
index: to add an entry to the index (comma separated)

Example:

.. faqref::
    :title: example of a blocref
    :label: id-you-can-choose6

    An example of code:

    ::

        print("mignon")

Which renders as:

example of a faqref

An example of code:

print("mignon")

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

.. faqreflist::
    :tag: dummy_example6
    :sort: title

Only blocs 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-choose6>' which gives something like link_to_blocref. The link must receive a name.

example of a faqref

An example of code:

print("mignon")

(original entry : sphinx_faqref_extension.py:docstring of sphinx_runpython.blocdefs.sphinx_faqref_extension.FaqRef, line 23)

node_class¶: alias of faqref_node

run()[source]¶: Calls run from sphinx_runpython.blocdefs.sphinx_blocref_extension.BlocRef and add defaut tag.

class sphinx_runpython.blocdefs.sphinx_mathdef_extension.MathDef(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶

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

title: a title for the math
tag: a tag to have several categories of math
lid or label: a label to refer to
index: to add an entry to the index (comma separated)

Example:

.. mathdef::
    :title: title
    :tag: definition or theorem or ...
    :lid: id (used for further reference)

    Description of the math

final_argument_whitespace = False¶: May the final argument contain whitespace?

has_content = True¶: May the directive have content?

node_class¶: alias of mathdef_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.

required_arguments = 0¶: Number of required directive arguments.

run()[source]¶: Builds the mathdef text.

Nodes¶

class sphinx_runpython.blocdefs.sphinx_blocref_extension.blocref_node(rawsource='', *children, **attributes)[source]¶: Defines blocref node.

class sphinx_runpython.blocdefs.sphinx_exref_extension.exref_node(rawsource='', *children, **attributes)[source]¶: Defines exref node.

class sphinx_runpython.blocdefs.sphinx_faqref_extension.faqref_node(rawsource='', *children, **attributes)[source]¶: Defines faqref node.

class sphinx_runpython.blocdefs.sphinx_mathdef_extension.mathdef_node(rawsource='', *children, **attributes)[source]¶: Defines mathdef node.