TeachBooks Fetch

TeachBooks Fetch#

A Sphinx extension that allows fetching of other HTML elements after DOM load.

This extension introduces two new directives:

  • fetch: Fetches content from a specified reference and inserts it into the rendered document.

  • click-to-fetch: Creates a clickable element that, when clicked, fetches content from a specified reference and inserts it into the rendered document.

The extension is designed to be used for the HTML output of Jupyter Book and Sphinx projects, and can be easily installed and activated as described below.

Installation#

pip install teachbooks-fetch

Activation#

Jupyter Book#

Add the extension to your _config.yml:

sphinx:
  extra_extensions:
    - teachbooks_fetch

Sphinx#

Add the extension to your conf.py:

extensions = [
    # ...
    'teachbooks_fetch',
]

Configuration#

Currently no configuration options are available for this extension.

Usage#

Fetch Directive#

The fetch directive allows you to fetch content from a specified reference and insert it into the rendered document.

Minimal usage (MyST syntax):

:::{fetch} <ref>
:::

Replace <ref> with code that generates a reference to the content you want to fetch. This can be one of the following:

  • A markdown style link, e.g. [link text](url#id).

  • An internal reference using the roles ref, numref, prf:ref (see Sphinx Proof) or bdg-link-<name> (see Sphinx Design).

  • A HTML link, e.g. <a href="url#id">link text</a>.

This will, initially, render a placeholder admonition with the following base MyST code:

:::{admonition} Fetching <ref>
:class: fetch
Content loading...
:::

In the placeholder the original reference/link is disabled.

After the DOM has loaded, the extension will attempt to fetch the content from the specified reference and replace the placeholder with the fetched content. If the fetch fails, the content of the placeholder will be updated to indicate that the fetch failed.

If preferred, you can also specify the content of the placeholder by including content in the directive:

:::{fetch} <ref>
This content will be shown while the fetch of [!a!] is in progress.
:::

Here [!a!] will be replaced with reference given in the directive argument.

If preferred, you can also specify the title of the placeholder by including the title option:

:::{fetch} <ref>
:title: Searching for [!a!]
:::

Here [!a!] will again be replaced with reference given in the directive argument.

If preferred, you can also specify additional CSS classes for the placeholder by including the class option:

:::{fetch} <ref>
:class: my-custom-class
:::

The special CSS class cancel-fetch can be used to indicate that the fetch should not be performed and that the placeholder should be rendered as-is.

Click-to-Fetch Directive#

The click-to-fetch directive allows you to create a clickable element that, when clicked, fetches content from a specified reference and inserts it into the rendered document.

Minimal usage (MyST syntax):

:::{click-to-fetch} <ref>
:::

This will, initially, render a placeholder admonition with the following base MyST code:

:::{admonition} Click to fetch <ref>
:class: fetch click-to-fetch
Waiting for a click...
:::

All options, content and behavior for the fetch directive are also available for the click-to-fetch directive. The only difference is that the click-to-fetch directive will not attempt to fetch the content until the user clicks on the placeholder.

If the click-to-fetch behavior is preferred without changing the default placeholder, you can also use the fetch directive with the click-to-fetch class.

Fetch rules#

The extension will attempt to fetch the content from the specified reference using the following steps:

  1. Extract the URL and ID from the reference.

  2. Attempt to fetch the content from the URL and extract the element with the specified ID from the fetched HTML.

This fetches the specified element all it’s child elements as-is. This means that no CSS files nor JavaScript files will be fetched. This also means that if the fetched element contains any references, these will not be resolved and will be rendered as-is and might result in broken links.

Examples#

Fetch Directive#

An example of the fetch directive with a reference to a figure with the name sticky_basic:

:::{fetch} {numref}`sticky_basic`
:::

Before fetching, the placeholder of the fetch directive will be:

Fetching Fig. 131

Content loading…

After successfully fetching the content from the specified reference, the placeholder will be replaced with the fetched content, in this case resulting in:

Fetching Fig. 131

Content loading…

If the fetch fails, the content of the placeholder will be updated to indicate that the fetch failed:

Failed to fetch Fig. 131

Fetching failed.

Click-to-Fetch Directive#

An example of the click-to-fetch directive with a reference to a figure with the name sticky_basic:

:::{click-to-fetch} {numref}`sticky_basic`
:::

The placeholder of the click-to-fetch directive will be:

Click to fetch Fig. 131

Waiting for a click…

Click on the above placeholder to fetch the content from the specified reference.

Contribute#

This tool’s repository is stored on GitHub. If you’d like to contribute, you can create a fork and open a pull request on the GitHub repository.