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$.
```

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

Control parameters

2D Specific parameters

3D Specific parameters

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.