Elements

Elements#

Document metadata#

.. metadata::#

This directive allows adding document metadata to a page. The content of the directive is a YAML document which is converted to a Python dict and merged into the document metadata.

In addition to Sphinx-specific metadata fields, the following top-level keys are interpreted.

exec

A mapping of per-language configuration for client-side code execution.

exec:
  python:
    packages: [sqlite3]

scripts

A list of scripts to reference from the page header through <script> elements. The list items can be either strings (the URL of the script) or maps. For maps, the src key specifies the URL of the script, and other keys are added to the <script> element. Relative URLs are resolved relative to the _static directory.

scripts:
  - classic-script.js
  - src: module-script.js
    type: module
  - https://code.jquery.com/jquery-3.7.1.min.js

styles

A list of CSS stylesheets to reference from the page header through <link> elements. The list items can be either strings (the URL of the stylesheet) or maps. For maps, the src key specifies the URL of the stylesheet, and other keys are added to the <link> element. Relative URLs are resolved relative to the _static directory.

styles:
  - custom-styles.css
  - src: print-styles.css
    media: print
  - https://example.com/styles.css

Default directive options#

.. defaults:: directive#

This directive sets default options for a directive type for the current document, starting from the current location. All directives of the given type that follow the defaults block take their default option values from that block. Options that are specified in the directive itself override the default.

A document can contain multiple defaults blocks for the same directive type. Each occurrence replaces the previous one, i.e. they don't combine.

```{exec} python
# Use the directive's default options
```

```{defaults} exec
:when: load
:class: hidden
```

```{exec} python
# Use ':when: load' and ':class: hidden'
```

```{exec} python
:when: click
# Use ':when: click' and ':class: hidden'
```

```{defaults} exec
:when: never
```

```{exec} python
# Use ':when: never' and no :class:
```

Solution#

.. solution:: [title]#

This directive adds an admonition of type solution. The title defaults to "Solution", and the body is collapsed by default.

The solutions: key in the document metadata controls how solutions are displayed.

show (default): Solutions are shown on the page.
hide: Solutions are hidden when the page loads. They can be shown or hidden with the / button in the navbar.
dynamic: Solutions are hidden by default, but can be made visible to everyone in real-time by members of the group solutions:show using the / button.

Options

:class: name [name...] (IDs)#: A space-separated list of CSS classes to add to the admonition. The default is note dropdown.

:name: name (ID)#: A reference target for the admonition.

:expand:#: When set, the admonition is expanded by default.

:show:#: When set, the admonition is always shown, even if solutions are hidden or removed.

IFrame#

.. youtube:: id#: This directive adds an <iframe> element loading a YouTube video. The argument is the ID of the video, e.g. aVwxzDHniEw. All the options of iframe are supported.

.. iframe:: url#

This directive adds an <iframe> element loading the given URL.

Options

:allow: directive; [directive; ...]#

The permission policy for the <iframe> (supported directives). The default is:

autoplay; clipboard-write; encrypted-media; fullscreen; picture-in-picture;
  screen-wake-lock; web-share

:class: name [name...] (IDs)#: A space-separated list of CSS classes to add to the <iframe>.

:credentialful:#: Indicate that the <iframe> should not be loaded in credentialless mode. The default is credentialless mode.

:referrerpolicy: value#: Indicate the referrer to send when fetching the <iframe> source (supported values).

:sandbox: token [token ...]#: Control the restrictions applied to the content embedded in the <iframe> (supported tokens).

:style: property: value; [property: value; ...]#: CSS styles to apply to the <iframe>, e.g. width: 80%;.

:title: text#: A concise description of the content of the <iframe>, typically used by assistive technologies.

Code execution#

See "Code execution".

Numbering#

:num:#

This role performs automatic numbering, optionally creating reference targets. The role content is either a label (e.g. {num}`label`) or an explicit title and a label (e.g. {num}`Exercise %s<label>`). In the latter case, the title must contain the string %s, which gets substituted with the number.

The label is composed of a counter identifier and an optional target name, separated by :. Distinct identifiers are numbered separately, and the counters persist across pages. Instances with a target (e.g. {num}`ex:target`) can be referenced with the numref role (e.g. {numref}`ex:target`).

## Exercise {num}`ex:intro`

As an introduction to ...

## Exercise {num}`ex`

After completing {numref}`exercise %s<ex:intro>`, ...

Quizz#

.. quizz::#

This directive adds an interactive quizz. It can contain arbitrary text and markup, as well as quizz-input roles to indicate where input fields should be placed and what the correct answers are. The toolbar on the right allows controlling the quizz.

: Check the provided answers. When all the answer fileds are correct, the quizz is locked.
: Clear the answer fields and unlock the quizz.

Options

:class: name [name...] (IDs)#: A space-separated list of CSS classes to add to the outer container.

:quizz-input:#

This role defines an <input> field. The text of the role is the solution for this field. The role normally isn't used as-is; instead, new roles are derived from it with role directives, which allows setting the options below and controlling the appearance and behavior of the fields.

For example, the following block defines a field role that places quizz inputs having a width of 3rem and aligning their text centered. The field role can then be used in quizz directives that follow its definition.

```{role} field(quizz-input)
:style: width: 3rem; text-align: center;
```

```{quizz}
| $a$ | $b$ | $a + b$    |
| :-: | :-: | :--------: |
|  1  |  2  | {field}`3` |
```

Note that such custom roles only apply to the document in which they are defined, and can be redefined multiple times in the same document.

Options

:check: name [name ...] (IDs)#

A list of checks to apply to answers and / or solutions to check if they match. The user's answer and the solution are passed to each check in turn, and it returns a potentially modified answer and solution. The final check should return a boolean indicating if the answer and solution match. The following checks are available:

default: The default check. Equivalent to trim equal.
split: Split the solution at commas (,). This changes the solution to an Array of strings.
trim: Trim whitespace at the beginning and end of the answer and solution.
lowercase: Convert the answer and solution to lowercase.
uppercase: Convert the answer and solution to uppercase.
equal: Return true iff the answer and solution compare equal, or if the solution is an Array and includes the answer.

Custom checks can be implemented by importing the tdoc/quizz.js module and extending the checks object. Check functions take as arguments the field being checked (an HTMLElement), the user's answer and the solution, and return the modified answer and solution or a boolean.

<script type="module">
const quizz = await tdoc.import('tdoc/quizz.js');
quizz.checks.nowhitespace = (field, answer, solution) => {
    return [answer.replace(/\s+/g, ''), solution];
};
</script>

:right: [property: value; ...]#: Applies a float: right; style to the <input>, so that it moves to the right of the text. Additional styles can optionally be provided as the value of the option, e.g. width: 35%;.

:style: property: value; [property: value; ...]#: CSS styles to apply to the <input>, e.g. width: 35%;.

Poll#

.. poll:: id#

This directive adds a live audience poll. The poll identifier id is required and its value must be unique across the site. The content of the directive is composed of the question, followed by a bullet list, where each list item becomes an answer. Both the question and the answers can contain arbitrary markup. Answers can optionally be marked as solutions by prefixing them with : (the prefix is removed).

Polls can be controlled by members of the group polls:control, using the buttons in the toolbar.

/ : Open or close the poll. Closed polls don't accept votes.
/ : Show or hide the poll results.
/ : Show or hide the solutions.
: Clear the poll results.

Voting on polls doesn't require any permissions. Polls are single-choice by default (:mode: single): selecting a different answer de-select a previously selected one, and re-selecting the selected answer un-selects it. Setting :mode: multi enables voters to select multiple answers.

Options

:mode: value (single | multi)#: The poll mode: single answer (single, the default) or allow multiple answers (multi).

:number: value (none | decimal | lower-alpha | upper-alpha)#: The answer numbering: no numbering (none), using decimal numbers (decimal), using lowercase letters (lower-alpha) or using uppercase letters (upper-alpha, the default).

:close-after: value (duration | never)#: The duration after opening when the poll should be closed automatically. The value is of the form 2h35m42s or never. The default is 15 minutes.

:class: name [name...] (IDs)#: A space-separated list of CSS classes to add to the outer container.

Elements

Contents

Elements#

Document metadata#

Default directive options#

Solution#

IFrame#

Code execution#

Numbering#

Quizz#

Poll#