Live code blocks

With SAGE_LIVE_DOC=yes, this extension turns the examples of the documentation into code blocks that the reader can execute, using jupyter-sphinx. Otherwise it makes the jupyter-sphinx directives no-ops.

class sage_docbuild.ext.livedoc.Ignore(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: SphinxDirective

has_content = True

May the directive have content?

run()

class sage_docbuild.ext.livedoc.SagecodeTransform(document, startnode=None)

Bases: SphinxTransform

Transform a code block to a live code block enabled by jupyter-sphinx.

Effectively a code block like:

EXAMPLE::

    sage: 1 + 1
    2

is transformed into:

EXAMPLE::

    sage: 1 + 1
    2

.. ONLY:: html

    .. JUPYTER-EXECUTE::
        :hide-code:
        :hide-output:
        :raises:
        :stderr:

        1 + 1

enabling live execution of the code.

apply()

default_priority = 170

Numerical priority of this transform, 0 through 999 (override).

sage_docbuild.ext.livedoc.ignore_jupyter_directives(app)

Make the directives of jupyter-sphinx do nothing.

Sphinx sets an extension up in the order of extensions, where jupyter-sphinx comes after this one, so registering the directives here would leave the ones of jupyter-sphinx in place; they are registered once every extension is set up instead. Executing the examples then needs a Sage kernel, which a documentation build has no reason to require.

sage_docbuild.ext.livedoc.setup(app)

Register this extension with Sphinx.