code

Customised .. code-block:: directive with an adjustable indent size.

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

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

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

Usage

.. code-block:: [language]
.. sourcecode:: [language]

Customised .. code-block:: directive with an adjustable indent size.

:tab-width: width (integer)

Sets the size of the indentation in spaces.

All other options from code-block are available, see the Sphinx documentation for details.

Examples

.. code-block:: python

    def print(text):
        sys.stdout.write(text)

def print(text):
    sys.stdout.write(text)


.. code-block:: python
    :tab-width: 8

    def print(text):
        sys.stdout.write(text)

def print(text):
        sys.stdout.write(text)

.. code-cell:: [language]
.. output-cell:: [language]

Customised .. code-block:: directives which display an execution count to the left of the code block, similar to a Jupyter Notebook cell.

New in version 2.6.0.

:execution-count: count (positive integer)

The execution count of the cell.

All other options from the code-block directive above are available.

Examples

.. code-cell:: python
    :execution-count: 1

    def print(text):
        sys.stdout.write(text)

    print("hello world")

.. output-cell::
    :execution-count: 1

    hello world
In [1]:
def print(text):
    sys.stdout.write(text)

print("hello world")
[1]:
hello world


.. code-cell:: python
    :execution-count: 2
    :tab-width: 8

    def print(text):
        sys.stdout.write(text)
In [2]:
def print(text):
        sys.stdout.write(text)

See also

nbsphinx, which inspired these directives and provides additional functionality for integrating Jupyter Notebooks with Sphinx.

API Reference

Classes:

CodeBlock(name, arguments, options, content, ...)

Directive for a code block with special highlighting or line numbering settings.

CodeCell(name, arguments, options, content, ...)

Customised code block which displays an execution count to the left of the code block, similar to a Jupyter Notebook cell.

OutputCell(name, arguments, options, ...)

Variant of CodeCell for displaying the output of a cell in a Jupyter Notebook.

Prompt([rawsource, text])

Represents a cell prompt for a CodeCell and OutputCell.

Functions:

visit_prompt_html(translator, node)

Visit a Prompt node with the HTML translator.

visit_prompt_latex(translator, node)

Visit a Prompt node with the LaTeX translator.

copy_asset_files(app[, exception])

Copy additional stylesheets into the HTML build directory.

configure(app, config)

Configure sphinx_toolbox.code.

setup(app)

Setup sphinx_toolbox.code.
class CodeBlock(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Bases: CodeBlock

Directive for a code block with special highlighting or line numbering settings.

The indent_size can be adjusted with the :tab-width: <int> option.

option_spec = {'caption': <function unchanged_required>, 'class': <function class_option>, 'dedent': <class 'int'>, 'emphasize-lines': <function unchanged_required>, 'force': <function flag>, 'lineno-start': <class 'int'>, 'linenos': <function flag>, 'name': <function unchanged>, 'tab-width': <class 'int'>}

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

run()[source]

Process the content of the code block.

Return type:

List[Node]

class CodeCell(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Bases: CodeBlock

Customised code block which displays an execution count to the left of the code block, similar to a Jupyter Notebook cell.

The indent_size can be adjusted with the :tab-width: <int> option.

The execution count can be set using the :execution-count: <int> option.

New in version 2.6.0.

option_spec = {'caption': <function unchanged_required>, 'class': <function class_option>, 'dedent': <class 'int'>, 'emphasize-lines': <function unchanged_required>, 'execution-count': <function positive_int>, 'force': <function flag>, 'lineno-start': <class 'int'>, 'linenos': <function flag>, 'name': <function unchanged>, 'tab-width': <class 'int'>}

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

run()[source]

Process the content of the code block.

Return type:

List[Node]

class OutputCell(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Bases: CodeCell

Variant of CodeCell for displaying the output of a cell in a Jupyter Notebook.

The indent_size can be adjusted with the :tab-width: <int> option.

The execution count can be set using the :execution-count: <int> option.

New in version 2.6.0.

class Prompt(rawsource='', text='', *children, **attributes)[source]

Bases: General, FixedTextElement

Represents a cell prompt for a CodeCell and OutputCell.

New in version 2.6.0.

visit_prompt_html(translator, node)[source]

Visit a Prompt node with the HTML translator.

New in version 2.6.0.

Parameters:

  • translator (HTML5Translator)

  • node (Prompt)

visit_prompt_latex(translator, node)[source]

Visit a Prompt node with the LaTeX translator.

New in version 2.6.0.

Parameters:

  • translator (LaTeXTranslator)

  • node (Prompt)

copy_asset_files(app, exception=None)[source]

Copy additional stylesheets into the HTML build directory.

New in version 2.6.0.

Parameters:

  • app (Sphinx) – The Sphinx application.

  • exception (Optional[Exception]) – Any exception which occurred and caused Sphinx to abort. Default None.

configure(app, config)[source]

Configure sphinx_toolbox.code.

New in version 2.9.0.

Parameters:

  • app (Sphinx) – The Sphinx application.

  • config (Config)

setup(app)[source]

Setup sphinx_toolbox.code.

New in version 1.0.0.

Parameters:

app (Sphinx) – The Sphinx application.

Return type:

SphinxExtMetadata