Examples with executable code

Examples with executable code#

Introduction#

This Sphinx extension provides an interface to examples with executable code.

This extension includes code adapted from sphinx-exercise.

Installation#

To install the Sphinx-Code-Examples, follow these steps:

Step 1: Install the Package

Install the Sphinx-Code-Examples package using pip:

pip install sphinx-code-examples

Step 2: Add to requirements.txt

Make sure that the package is included in your project’s requirements.txt to track the dependency:

sphinx-code-examples

Step 3: Enable in _config.yml

In your _config.yml file, add the extension to the list of Sphinx extra extensions:

sphinx: 
    extra_extensions:
        - sphinx_code_examples

Documentation#

Further documentation for this extension is available in the TeachBooks manual.

Configuration#

The extension provides several configuration values, which can be added to _config.yml:

sphinx: 
    config:
        sphinx_codex_name:                 ""    # default value
        sphinx_codex_style_from_proof:     true  # default value
        sphinx_codex_icon_from_proof:      false # default value
        sphinx_codex_merge_with_proof:     false # default value

  • sphinx_codex_name: "" (default) or string:

    • if "" all codex directives will have the title “Code example” and will be referred to as “Code example” in the text.

    • if a string is provided, all codex directives will have the title set to that string and will be referred to as that string in the text.

  • sphinx_codex_style_from_proof: true (default) or false:

    • if true, the CSS color style of the codex directive will be taken from the prf:example directive from the sphinx-proof extension.

    • if false, the CSS color style of the codex directive will be taken from the general admonition directive.

  • sphinx_codex_icon_from_proof: true (default) or false:

    • if true, the icon of the codex directive will be taken from the prf:example directive from the sphinx-proof extension.

    • if false, the icon of the codex directive will be set to .

  • sphinx_codex_merge_with_proof: false (default) or true:

    • if true, the codex directive will be merged with the prf:example directive from the sphinx-proof extension. This means that:

      • All codex directives and prf:example directives will be named “Example” (unless set otherwise) and styled (color and icon) as defined by the prf:example directive from the sphinx-proof extension.

      • The numbering of the codex directives will be merged with the numbering of the prf:example directives from the sphinx-proof extension.

    • if false, the codex directive will not be merged with the prf:example directive from the sphinx-proof extension. This means that:

      • All codex directives will be named “Code example” (unless set otherwise) and styled (color and icon) as defined by the sphinx_codex_style_from_proof and sphinx_codex_icon_from_proof configuration values.

      • The numbering of the codex directives will be independent of the numbering of the prf:example directives from the sphinx-proof extension.

Usage#

This extension provides three directives:

  • codex

  • codex-start

  • codex-end

codex directive#

Warning

Although this directive is called codex, it does not imply that the code is executable. It is simply a directive to create the possibility to use one extension for both executable and non-executable (code) examples.

The codex directive is used to create an example. It can be used as with the following minimal syntax:

:::{codex}
:label: example-codex

This is an example from sphinx-codex. It is a non-code example.

:::

This will be rendered as

Code example 1

This is an example from sphinx-codex. It is a non-code example.

codex-start and codex-end directives#

Warning

This extension does not provide a way to execute code. The codex-start and codex-end directives are used to create a code example that may contain executable code, but the code itself is not automatically executable.

The codex-start and codex-end directives are used to create a code example that may contain executable code. It can be used as with the following minimal syntax:

:::{codex-start}
:label: example-code

Executing the next piece of code
:::

print("Hello from a code cell in Sphinx Book!")

should be a piece of cake.

:::{codex-end}
:::

This will be rendered as

Code example 2

Executing the next piece of code

print("Hello from a code cell in Sphinx Book!")

should be a piece of cake.

References#

References to codex examples can be made using the ref role. The label of the example is used as the reference target. Examples can be referenced as

{ref}`example-code` shows a code example from sphinx-codex.

{ref}`example-codex` shows a non-code example from sphinx-codex.

which will be rendered as

Code example 2 shows a code example from sphinx-codex.

Code example 1 shows a non-code example from sphinx-codex.

Contents