Extension

Sphinx extensions

t-doc is based on Sphinx, which provides many extension mechanisms to add roles and directives or extend the build process. This doesn't require creating a separate Python package, and can be done within a site repository.

Please refer to the Sphinx documentation to extend t-doc via Sphinx.

t-doc extensions

The roles and directives provided by t-doc are intended to cover the most common use cases. For more specific uses, they provide extension points that can be used from site repositories to augment their capabilities.

Many roles and directies generate custom <tdoc-*> HTML elements that are rendered asynchronously, so they may not be complete by the time the DOMContentLoaded fires. This section presents two methods for safely adding functionality to <tdoc-*> elements.

The following tables shows how roles and directives map to custom elements.

Role / directive	Element	Element class
chartjs	<tdoc-dyn type="chartjs">	DynElement
exec	<tdoc-exec>	ExecElement
jsxgraph	<tdoc-dyn type="jsxgraph">	DynElement
mermaid	<tdoc-dyn type="mermaid">	DynElement
poll	<tdoc-poll>	PollElement
quiz	<tdoc-quiz>	QuizElement

Lifecycle hooks

TdocElement.extend() allows registering a handler object whose methods are called at different stages of the lifecycle of <tdoc-*> elements. In particular, the ready() method is called when t-doc has finished rendering the element.

The following example adds a button to exec blocks having the class extend-inspect that displays the content of the block.

<p>This is a paragraph.</p>
<p>This is another paragraph.</p>

Enumeration

Selected <tdoc-*> elements on a page can be enumerated with qsaReady(). The function waits for the DOM to be loaded and for the elements to be ready before yielding them asynchronously. The returned generator must therefore be iterated with for await.

The following example adds a button to exec blocks having the class enum-inspect that displays the content of the block.

<p>This is a paragraph.</p>
<p>This is another paragraph.</p>

JavaScript libraries

tdoc/early.js

This script (source) is run before most scripts and modules are loaded, and exposes functionality via the tdoc object accessible in the global namespace.

Globals

tdoc

This object is pre-loaded into the global namespace and provides functionality that is needed outside of JavaScript modules, and therefore cannot be placed into a module.

Functions

tdoc.import(...modules)

Import one or more JavaScript modules.

Arguments:

• modules (string[]) -- The modules to import, as paths relative to the _static directory.

Returns:

A Promise resolving to the module namespace if a single argument was provided, or to an Array of module namespaces if multiple arguments were provided.

tdoc/core.js

This module (source) provides functionality used across all of t-doc.

Module globals

core.domLoaded

A Promise that resolves when the DOM content has been fully loaded, i.e. the DOMContentLoaded event has been dispatched on the document.

Functions

core.qs(el, selector)

An short alias for el.querySelector(selector). It gracefully handles the case where el is undefined or null.

Arguments:

• el (HTMLElement|DocumentFragment) -- The DOM object to query.

• selector (string) -- A CSS selector.

Returns:

The first matching element, or null if there are none.

core.qsa(el, selector)

An short alias for el.querySelectorAll(selector). It gracefully handles the case where el is undefined or null by returning an empty NodeList.

Arguments:

• el (HTMLElement|DocumentFragment) -- The DOM object to query.

• selector (string) -- A CSS selector.

Returns:

A NodeList of elements matching the selector.

core.qsaReady(el, selector)

Query DOM elements below el matching selector once, and yield them asynchronously. Standard elements are yielded immediately after the DOM has been loaded; custom <tdoc-*> elements are yielded as they become ready.

Arguments:

• el (HTMLElement|DocumentFragment) -- The DOM object to query.

• selector (string) -- A CSS selector.

Returns:

An asynchronous iterator that yields the matching elements.

core.html(tmpl, ...values)

A tag function that safely generates a DocumentFragment via a tagged template. Substitutions are HTML-escaped, except for DocumentFragment and Element instances, whose outerHTML is substituted as-is.

const value = "x < y";
const el = html`The variable <code>value</code> contains: ${value}`;

Returns:

A DocumentFragment.

core.elmt(tmpl, ...values)

A tag function that safely generates an Element via a tagged template. Substitutions are HTML-escaped, except for DocumentFragment and Element instances, whose outerHTML is substituted as-is.

Returns:

The first Element parsed from the string.

core.htmle(tmpl, ...values)

A tag function that safely generates an HtmlError via a tagged template. Substitutions are HTML-escaped, except for DocumentFragment and Element instances, whose outerHTML is substituted as-is.

Returns:

An HtmlError.

core.on(el)

Return a Proxy object that sets event listeners on an element. This is a more compact way to call el.addEventListener(). To set a listener, call the method on the proxy that corresponds to the event, and pass the listener function as an argument. The methods return the Proxy, so multiple liseteners can be set with chained calls.

on(qs(document, 'button'))
    .click(() => alert("Clicked"))
    .mouseenter(() => alert("Mouse entered"))
    .mouseleave(() => alert("Mouse left"));

Arguments:

• el (HTMLElement) -- The DOM element on which to set event listeners.

Returns:

A Proxy object.

core.showAlert(message, kind='success')

Show an alert at the top of the page. If the message is an HtmlError, kind is taken from the error and defaults to 'danger'.

Arguments:

• message (string|Error) -- The message to display.

• kind (string) -- The kind of message to display.

Classes

class core.HtmlError(html, options)

An Error subclass that carries its message as an HTML element or fragment. It is useful to generate rich error messages for display e.g. with showAlert().

Properties

HtmlError.html

The HTML element or fragment provided to the constructor.

HtmlError.kind

The kind of alert to show for this error.

Methods

HtmlError.[static] of(err)

Create an HtmlError from an Error or a string.

Arguments:

• err (Error|string) -- The error or error message from which to construct the HtmlError. If err is already an HtmlError, it is returned unchanged.

HtmlError.as(kind)

Specify the kind of alert to show for this error.

Retunrs:

The error itself.

class core.TdocElement()

The base class for all custom <tdoc-*> elements.

Properties

TdocElement.ready

A Promise that resolves to the element when it becomes ready.

Methods

TdocElement.[static] extend(name, handler)

Extend a custom <tdoc-*> element type. This method registers a handler whose methods are called at different stages of the lifecycle of element instances.

Arguments:

• name (string) -- The name of the custom element type.

• handler (Object) -- An object of lifecycle methods.

The following methods can be defined on handler:

• ready(el): Called when an element becomes ready.

class core.DynElement()

The class implementing <tdoc-dyn> custom elements. It extends TdocElement.

Properties

DynElement.type

The type of the directive, contained in the type attribute.

DynElement.name

The name of the block, contained in the name attribute, if the directive was named.

DynElement.args

The arguments provided in the directive content, contained in the args attribute. This is a serialized JSON object.

DynElement.controller

The controller object for the element. The type of the controller is specific to each directive.