Sphinx Extension: PRIME applets

Introduction

This extension provides an interface to include PRIME applets with relative ease.

What does it do?

This extension provides one Sphinx directives (applet) that can be used to quickly insert a PRIME applet.

Installation

To use this extension, follow these steps:

Step 1: Install the Package

Install the module sphinx-prime-applets package using pip:

pip install sphinx-prime-applets

Step 2: Add to requirements.txt

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

sphinx-prime-applets

Step 3: Enable in _config.yml

In your _config.yml file, add the extension to the list of Sphinx extra extensions (important: underscore, not dash this time):

sphinx: 
    extra_extensions:
        .
        .
        .
        - sphinx_prime_applets
        .
        .
        .

Applet directive

```{applet}
:url: lines_and_planes/normal_equation_plane_origin
:fig: Images/image_shown_in_print_version.svg
:name: name_that_is_used_to_refer_to_this_figure
:class: dark-light
:title: This title is shown when you full-screen the applet

A plane through the point $P$.
```

[!NOTE] The url parameter should be the part of the URL after /applet/. So if the full URL is https://openla.ewi.tudelft.nl/applet/lines_and_planes/normal_equation_plane_origin, you should set the parameter to lines_and_planes/normal_equation_plane_origin.

Setting the base URL

By default, the extension uses https://openla.ewi.tudelft.nl/applet/ as the base URL for the applets. If you want to change this, you can set the prime_applets_base_url configuration option in your Sphinx configuration file to the desired base URL. For example:

# In your Sphinx configuration file (e.g., conf.py)
prime_applets_base_url = "https://my-custom-url.com/applet/"

or in YAML format:

# In your Sphinx configuration file (e.g., _config.yml)
sphinx:
    config:
        prime_applets_base_url: "https://my-custom-url.com/applet/"

Parameters for an applet

Some parameters can be set for an applet. Only the url and name parameters are required; the rest is optional. It is recommended to add a status to the applet, which can be unreviewed, in-review or reviewed.

```{applet}
:url: lines_and_planes/normal_equation_plane_origin # Required url
:fig: Images/lines_and_planes/normal_equation_plane_origin.svg  # Image shown in print version
:status: reviewed # default is "unreviewed". Other options are "in-review" and "reviewed"
:name: Fig:InnerProduct:ProjectionVectorLine

A title that describes the applet
```

Optional parameters

[!NOTE] If the fig parameter is not defined, the code will insert the image provided by the applet itself as a fallback.

Control parameters

[!WARNING] Work in progress

2D Specific parameters

[!TIP] You should add split-* before the parameter to make it apply to the right scene

3D Specific parameters

[!TIP] You should add split-* before the parameter to make it apply to the right scene

Contribute

This tool's repository is stored on GitHub. If you'd like to contribute, you can create a fork and open a pull request on the GitHub repository.

The README.md of the branch manual is also part of the TeachBooks manual as a submodule.

Metadata

By default the applet directive adds metadata to the figure node it creates. This metadata includes information such as author, license, copyright, and source. This information is useful for documentation and attribution purposes. If you want to disable this feature, you can set the prime_applets_metadata configuration option to False in your Sphinx configuration file.

[!NOTE] This extension always loads the extension sphinx_metadata_figure as it depends on it to add metadata to the figures. This means that also the configuration options of that extension are available and if this is not desired, you must disable the workings of that extensions by applying appropriate settings in metadata_figure_settings in your Sphinx configuration file. See the documentation of the sphinx_metadata_figure extension for more information.