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]

page-break-avoid

A level or list of levels of sections in which page breaks should be avoided.

page-break-force

A level or list of levels of sections after which a page break should be forced.

print-styles

A CSS stylesheet URL to use when printing. Relative URLs are resolved relative to the _static directory. The following print stylesheets are provided:

tdoc/print.css: A simple style with page headers and footers.

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

subject

The subject covered by the document. This may be used by print stylesheets in headers or footers.

versions

A map overriding the versions of JavaScript dependencies on a page. The keys are dependency identifiers and the values can be either version numbers or full URLs. See deps.py for the list of dependencies and their default version. The versions can be overridden for a whole site via the tdoc_versions option in conf.py.

versions:
  polyscript: 0.17.30
  pyodide: https://cdn.jsdelivr.net/pyodide/v0.27.7/full

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.

Flex table#

.. flex-table::#

This directive defines an HTML <table> using a more flexible syntax than Markdown tables or other table directives. In particular, it allows assigning CSS classes to individual rows and cells, and allows cells to span multiple rows and / or columns. The directive content defines the content of the table, using the following syntax:

Each line of the directive content defines a row.
Each cell in a row starts with a | character.
A row can optionally start with attributes that are applied to the row. In addition to classes and identifiers, the following attributes are recognized:
- t: Determines if the row is a header row (h) or a body row (b). Consecutive header rows are grouped in a <thead>, while body rows are grouped in a <tbody>. Rows that don't specify a type use the type of the previous row. The default for the first row is b.
The content of a cell can optionally start with attributes that are applied to the cell. In addition to classes and identifiers, the following attributes are recognized:
- cols: Sets the colspan attribute of the cell tag.
- rows: Sets the rowspan attribute of the cell tag.
- t: Determines if the cell is a heading cell (h) or a data cell (d). Heading cells are rendered as <th>, and data cells are rendered as <td>. Cells that don't specify a type default to h in header rows and d in body rows.
The cell content is parsed as inline markup, i.e. it can include styling, inline math, etc. | characters within the cell content must be escaped as \|.

```{flex-table}
{t=h}|Name|Age|Shoe size
{t=b}|{t=h}Joe|23|43
     |{t=h}Jack|18|41
     |{t=h}Jim|{cols=2}unknown
```

Tables have no styling by default, but the following classes are set up in the stylesheet and can be used in the :class: option.

function-table: Formats the table as a function value and / or sign table. The following classes can be set on table cells:
- .l: Left-align the cell content.
- .r: Right-align the cell content.
- .g: Apply a grey background to the cell. Typically used where the function is undefined.
- .w: Sets min-width: 5rem on the cell.

Options

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

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

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.

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

Elements

Contents

Elements#

Document metadata#

Default directive options#

Solution#

Flex table#

IFrame#

Numbering#