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.

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 on a page can be shown or hidden by clicking the "Toggle solutions" button in the navbar.

By default, solutions are shown when loading the page. The default can be changed by setting hide-solutions: true in the document metadata.

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 via the toggle button.

IFrames

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