Attribution

This page originates from TeachBooks/sphinx-code-examples.git, version: main

User types

This section is useful for user type 3-5.

Sphinx Extension

Attribution

This page originates from TeachBooks/sphinx-code-examples.git, version: main

Examples with executable code and visuals

Introduction

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

This extension includes code adapted from sphinx-exercise.

Installation

To install the Sphinx-Code-Examples extension, 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 or false (default):

  • 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 (default) or to in case of an example with an alternative visual.

• 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.

As additional functionality, the codex directive supports adding visuals hosted on other websites such as YouTube as an alternative to traditional textual content of the examples. Only a visual can be defined for specific document languages. For example, to add a visual that only appears in English documents, but not in other translated docuemnts, add the option :en: <url> with <url> replaced by the url of the en visual. For each other language a new visual can be added using a similar option.

The next code generates an example with a visual for English documents but also for Dutch documents. As this document is in English, the English visual will be used.

:::{codex}
:label: example-codex-visual
:en: https://www.youtube.com/embed/B1J6Ou4q8vE?si=XZDT83fcR6W3Dxut
:nl: https://www.youtube.com/watch?v=iA61Z0BAI90&ab_channel=EasyDutch

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed dapibus, metus vitae pulvinar placerat, felis ante rhoncus est, eu dictum erat arcu vel ante. Sed rhoncus mauris vel mi pulvinar, vulputate dapibus leo ultricies. Phasellus orci magna, sodales eu ullamcorper quis, pharetra sodales nunc. Nullam tempus erat nisl, eu dictum felis gravida dignissim. In tempor interdum mattis. Sed mattis dignissim eros vel feugiat. Curabitur est enim, tristique et ornare id, scelerisque vehicula sem. Mauris semper tortor nisl, quis accumsan quam porta a. Quisque venenatis magna id libero semper cursus.

Donec nec accumsan massa. Morbi viverra congue molestie. Fusce maximus et sem a iaculis. In vel tempor tortor. Phasellus convallis tortor et tempor porta. Phasellus ut aliquet lectus. Nunc facilisis est consectetur libero ultricies pulvinar.

:::

The result:

Code example 2

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed dapibus, metus vitae pulvinar placerat, felis ante rhoncus est, eu dictum erat arcu vel ante. Sed rhoncus mauris vel mi pulvinar, vulputate dapibus leo ultricies. Phasellus orci magna, sodales eu ullamcorper quis, pharetra sodales nunc. Nullam tempus erat nisl, eu dictum felis gravida dignissim. In tempor interdum mattis. Sed mattis dignissim eros vel feugiat. Curabitur est enim, tristique et ornare id, scelerisque vehicula sem. Mauris semper tortor nisl, quis accumsan quam porta a. Quisque venenatis magna id libero semper cursus.

Donec nec accumsan massa. Morbi viverra congue molestie. Fusce maximus et sem a iaculis. In vel tempor tortor. Phasellus convallis tortor et tempor porta. Phasellus ut aliquet lectus. Nunc facilisis est consectetur libero ultricies pulvinar.

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 3

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 3 shows a code example from sphinx-codex.

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