Configuration

Configuration#

Document metadata#

.. metadata:: [format]#

This directive sets document metadata at the page level. The content of the directive is parsed into a Python dict and merged into the document metadata. The following format values are supported:

json: The content is a JSON5 object (without enclosing {}).
yaml (default): The content is a YAML document.

The metadata conf.py option defines site-wide default document metadata.

In addition to Sphinx-specific metadata fields, t-doc uses the following document metadata fields for per-page configuration.

chartjs:: A map of config defaults for chartjs charts.
date:: The date to use in headers and footers when printing. Defaults to the current date.
exec:: A map of per-language configuration for client-side code execution.
```
exec:
  python:
    packages: [sqlite3]
```
hide:: A set of elements to hide on the page.
jsxgraph:: A map of config defaults for jsxgraph graphs.
mathjax:: A map of MathJax configuration overrides.
- output:: The default output processor (chtml, svg). The default is svg.
mermaid:: A map of config properties for mermaid diagrams.
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.
points:: Defines how point values are formatted.
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
  - Header, left: The value of the subject metadata.
  - Header, right: The first-level title of the document.
  - Footer, left: The site author.
  - Footer, center: The page number and the total number of pages.
  - Footer, right: The value of the date metadata.
- tdoc/print-exam.css
  - Header, left: The value of the subject metadata.
  - Header, center: The first-level title of the document.
  - Header, right: The value of the date metadata.
  - Footer, left: The site author.
  - Footer, center: The page number and the total number of pages.
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
```
solutions:: Controls how solutions are displayed.
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.
```
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 from 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
# Uses the directive's default options
```

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

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

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

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

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

Sphinx configuration#

The Sphinx configuration is located in the file docs/conf.py. The options that aren't specific to t-doc are described in the Sphinx documentation (configuration, extensions). t-doc defines additional options described below.

t-doc provides defaults for many options in the tdoc.common.defaults module, which is intended to be wildcard-imported into conf.py.

from tdoc.common.defaults import *

license#

Type:: str
Default:: ""

The license under which the site content is distributed.

license_url#

Type:: str
Default:: Set automatically for some licenses, "" otherwise.

The URL of a page showing the full content of the license under which the site content is distributed.

metadata#

Type:: dict
Default:: {}

Site-wide default document metadata.

tdoc#

Type:: dict
Default:: {}

A dict that is converted to JSON and made available to JavaScript as tdoc.conf.

tdoc_api#

Type:: str
Default:: ""

The base URL of the t-doc API server. When empty, the URL is set automatically for t-doc.org and its subdomains.

tdoc_repos#

Type:: str
Default:: "https://rc.t-doc.org/"

The base URL of the site repositories.

tdoc_domain_storage#

Type:: str
Default:: {}

t-doc sites are deployed as sub-domains (e.g. common.t-doc.org) of an apex domain (e.g. t-doc.org). The apex site provides access to a subset of its localStorage to sub-domains, e.g. for login information. This option configures the domain-wide storage; the following keys can be set:

origin: The origin of the apex domain (default: https://t-doc.org). This option must be set on all sites.
allowed_origins: A regexp matching origins that are allowed to read and write to domain-wide storage. This option must be set on the apex site.
allowed_keys: The storage keys that can be read and written. This option must be set on the apex site.

See the configuration for t-doc.org for an example.

tdoc_enable_sab#

Type:: str, one of no, cross-origin-isolation, sabayon
Default:: "no"

The strategy to use to work around the absence of SharedArrayBuffer.

no: Don't set up a workaround.
cross-origin-isolation: Install a service worker that adds cross-origin isolation headers.
sabayon: Install a service worker running Sabayon.

CLI and API configuration#

The tdoc CLI and the API server read their configuration from a TOML file.

By default, the CLI looks for a file named tdoc.local.toml starting in the current directory and moving up the hierarchy. The default can be overridden with the --config option or the TDOC_CONFIG environment variable.
The API server reads the file tdoc.local.toml at the root of the common repository.

If not specified otherwise, configuration values that represent paths interpret relative paths as relative to the directory containing the config file.

`[cors]`#

This table configures cross-origin resource sharing (CORS).

domain: The apex domain of the deployment. The API server allows cross-origin HTTPS requests from this domain and all direct subdomains.

`[import-files]`#

This table defines files to be copied from outside the repository. The files are copied by the local server whenever they change. This allows keeping sets of files in sync between repositories, while keeping the repositories hermetic.

The keys of the [import-files] table determine the destination directory below docs/_import into which the files are copied (using the same hierarchy as the source), and the values define the source files.

Table values use the following keys:
- src: The path to the directory containing the source files. Relative paths are interpreted relative to the directory containing the config file.
- include: An array of glob patterns matching paths relative to src of files to include in the import.
- exclude: An array of glob patterns matching paths relative to src of files to exclude from the import. If a file matches both include and exclude, then it isn't imported.

String values are a shortcut for:

KEY = {src = "VALUE", include = ["**/*.export/**', '**/*.export.*"], exclude = ["_import/**"]}

Example:

site1/tdoc.local.toml#

[import-files]
site2 = "../site2/docs"

`[logging]`#

This table configures the logging subsystem.

format (default: default_query_format): The format string to use for log query output.
level (default: "NOTSET"): The overall log level.
transport (default: "queue"): Either "queue" to run the log handlers in a separate thread and passing log records via a queue, or "none" to run the log handlers in-line with the log statements.

`[[logging.databases]]`#

These tables define logging handlers that store records in a SQLite database.

Common database options
enabled (default: true): Enables or disables the handler.
level (default: "NOTSET"): The log level for this handler.
flush_interval (default: 5): The interval in seconds at which queued log records are flushed to the database.
purge_interval (default: "1h"): The interval at which stored log records that are out of retention are removed from the database.
retain (default: "90d"): The stored log record retention. Log records that are older than the retention are remove from the database.

`[[logging.files]]`#

These tables define logging handlers that store records in text files.

compress (default: true): When true, compress log files after rotation.
enabled (default: true): Enables or disables the handler.
format (default: default_file_format): The format string to use for writing to the file.
level (default: "NOTSET"): The log level for this handler.
path: The path to the log file.
permissions (default: 0o600): The permissions to set on log files.
rotate: The log file rotation parameters, as a table with the following keys:
- when (default: "W6"): The type of rotation interval.
- interval (default: 1): The number of intervals after which to rotate the log file.
- keep (default: 4): The number of rotated files to keep.

`[logging.stream]`#

This table configures the logging handler that outputs log records to stderr.

enabled (default: true): Enables or disables the handler.
format (default: default_stream_format): The format string to use for output.
level (default: "NOTSET"): The log level for this handler.

`[[oidc.issuers]]`#

These tables configure OIDC issuers.

enabled (default: true): Enables or disables an issuer.
client_id: The client ID to use when communicating with the issuer.
client_secret: The client secret to use when communicating with the issuer.
create_users: An array of spec tables that define how to auto-create t-doc users from OIDC tokens. When an unknown user tries to log in, their OIDC token is matched against the claims in this array. The first matching entry causes a new t-doc user to be created. If no entries match, the login is rejected.
- claims: A table whose keys specify OIDC token keys, and values specify the allowed token values. String values are regexps matched against the token value. Other value types are compared for equality.
- username: The key of the OIDC token whose value should be used as the new user's username.
issuer: The issuer URI.
label: The label to use for the issuer in the login dialog.

The following example defines a Google issuer, with automatic user creation for users in the example.com domain whose email was verified, using their email address as a username.

[[oidc.issuers]]
label = "Google"
issuer = "https://accounts.google.com"
client_id = "123456789012-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6.apps.googleusercontent.com"
client_secret = "GOCSPX-0123456789abcdefghijklmnopqr"
create_users = [
   {claims = {hd = 'example\.com', email_verified = true}, username = "email"},
]

`[oidc.token]`#

This table configures options related to JSON Web Tokens (JWT).

algorithms (default: ["RS256"]): The set of JWT signature algorithms to accept.
verify_leeway_secs (default: 60): The maximum clock skew in seconds to accept when verifying JWTs.

`[repo]`#

This table configures options related to repository access.

bcrypt_rounds (default: 10): The number of rounds to use when encrypting generated repository passwords with bcrypt.

`[site]`#

This table configures options related to site repositories.

trusted (default: false): When true, site repositories are trusted. Untrusted sites can only be built via their own run.py script; building via a local clone of the common repository (development workflow) must be done in a sandbox.

`[store]`#

This table configures the database that stores site and user data.

Common database options
poll_interval (default: 1): The interval in seconds at which to poll the database for cross-process notifications.

Common database options#

path: The path to the database file.
pool_size (default: 16): The size of the read connection pool.
pragma: A table of pragmas to set on database connections.
timeout (default: 5): The timeout in seconds for waiting for a locked database.
write_isolation_level (default: "immediate"): The transaction behavior; one of "deferred", "exclusive" or "immediate".

Log format strings#

Log format strings are {}-based format strings that determine how log records should be formatted. The following attributes are available within the format string:

The LogRecord attributes.
ctx: A string representing the context where the log record was created. This is the thread name by default, but it can be set explicitly e.g. to a request identifier.
ctxc: An ANSI sequence setting a color based on the value of ctx.
levelc: A color value appropriate for the log level.
leveli: The first letter of the log level name.
The ANSI escape sequences defined in ansi_seqs.

`run.py` configuration#

The run.py script fetches its TOML configuration from config/run.toml in the common repository, and merges it with two optional files located in the same directory as the script, run.toml (versioned) and run.local.toml (unversioned). The local files override the remote one.

Top-level keys#

hermetic: When true, install the exact versions specified by the versioned requirements files. When false, only specify the version of the package itself, but not of its dependencies.
package: The name of the Python package to use.
version: The version of the Python package to use, either a version or a tag listed in the [tags] table, or "dev" to use an editable package (only relevant for the common repository).

`[defaults]`#

command: The default command and arguments to use when no command is specified.
command_*: Additional arguments to append to command. The values are appended in key order.
command-dev: The default command and arguments to use when no command is specified, and version is "dev".
command-dev_*: Additional arguments to append to command-dev. The values are appended in key order.

`[tags]`#

This table defines tags that can be used in version, typically to define release tracks. The keys are tag names, and the values are the versions corresponding to the tag.

Configuration

Contents

Configuration#

Document metadata#

Default directive options#

Sphinx configuration#

CLI and API configuration#

[cors]#

[import-files]#

[logging]#

[[logging.databases]]#

[[logging.files]]#

[logging.stream]#

[[oidc.issuers]]#

[oidc.token]#

[repo]#

[site]#

[store]#