rest_example

Directive to show example reStructuredText and the rendered output.

Enable sphinx_toolbox.rest_example by adding the following to the extensions variable in your conf.py:

extensions = [
    ...
    'sphinx_toolbox.rest_example',
    ]

For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .

Usage

.. rest-example::

Directive to show example reStructuredText and the rendered output.

:force: (flag)

If given, minor errors on highlighting are ignored.

:emphasize-lines: line numbers (comma separated numbers)

Emphasize particular lines of the code block:

:tab-width: number (number)

Sets the size of the indentation in spaces.

:dedent: number (number)

Strip indentation characters from the code block,

Example

.. rest-example::

    :source:`sphinx_toolbox/config.py`

    Here is the :source:`source code <sphinx_toolbox/config.py>`


:source:`sphinx_toolbox/config.py`

Here is the :source:`source code <sphinx_toolbox/config.py>`

sphinx_toolbox/config.py

Here is the source code

API Reference

Classes:

reSTExampleDirective(name, arguments, ...)

Directive to show some reStructuredText source, and the rendered output.

Functions:

make_rest_example(options, env, content)

Make the content of a reST Example node.

setup(app)

Setup sphinx_toolbox.rest_example.

Data:

rest_example_purger

Purger to track rest-example nodes, and remove redundant ones.
class reSTExampleDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Bases: SphinxDirective

Directive to show some reStructuredText source, and the rendered output.

Methods:

run()

Create the rest_example node.
has_content = True

Type:    bool

option_spec = {'dedent': <class 'int'>, 'emphasize-lines': <function unchanged>, 'force': <function flag>, 'tab-width': <class 'int'>}

Type:    Mapping[str, Callable[[str], Any]]

run()[source]

Create the rest_example node.

Return type:

List[Node]

make_rest_example(options, env, content)[source]

Make the content of a reST Example node.

Parameters:
Return type:

List[str]

rest_example_purger = Purger('all_rest_example_nodes')

Type:    Purger

Purger to track rest-example nodes, and remove redundant ones.

setup(app)[source]

Setup sphinx_toolbox.rest_example.

New in version 0.7.0.

Parameters:

app (Sphinx) – The Sphinx application.

Return type:

SphinxExtMetadata