assets

Role to provide a link to open a file within the web browser, rather than downloading it.

New in version 0.5.0.

Enable sphinx_toolbox.assets by adding the following to the extensions variable in your conf.py:

extensions = [
    ...
    'sphinx_toolbox.assets',
    ]

For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .

Usage

:asset:

Adds a link to a local file that can be viewed within the web browser. The file will be copied from the directory set in assets_dir to /_assets in the HTML output.

This is similar to the download role, but that role will download the file to the user’s computer instead. This role may be useful for PDFs, which most web browsers can display.

If the file can’t be found an error will be shown in the build output:

<page where the error occurred>: Asset file '<missing asset file name>' not found.

Asset

:asset:`hello_world.txt`

:asset:`hello_world <hello_world.txt>`

hello_world.txt

hello_world

Download

:download:`hello_world.txt <../assets/hello_world.txt>`

hello_world.txt

Configuration

assets_dir
Type: str
Required: False
Default: './assets'

The directory in which to find assets for the asset role.

API Reference

Functions:

asset_role(name, rawtext, text, lineno, inliner)

Adds a link to an asset.

visit_asset_node(translator, node)

Visit an AssetNode.

depart_asset_node(translator, node)

Depart an AssetNode.

setup(app)

Setup sphinx_toolbox.assets.

Classes:

AssetNode([rawsource, text])

Node representing a link to an asset.
asset_role(name, rawtext, text, lineno, inliner, options={}, content=[])[source]

Adds a link to an asset.

Parameters

  • name (str) – The local name of the interpreted role, the role name actually used in the document.

  • rawtext (str) – A string containing the entire interpreted text input, including the role and markup.

  • text (str) – The interpreted text content.

  • lineno (int) – The line number where the interpreted text begins.

  • inliner (Inliner) – The docutils.parsers.rst.states.Inliner object that called source_role(). It contains the several attributes useful for error reporting and document tree access.

  • options (Dict) – A dictionary of directive options for customization (from the role directive), to be interpreted by the function. Used for additional attributes for the generated elements and other functionality. Default {}.

  • content (List[str]) – A list of strings, the directive content for customization (from the role directive). To be interpreted by the function. Default [].

Return type

Tuple[Sequence[AssetNode], List[system_message]]

Returns

A list containing the created node, and a list containing any messages generated during the function.

class AssetNode(rawsource='', text='', *children, **attributes)[source]

Bases: reference

Node representing a link to an asset.

visit_asset_node(translator, node)[source]

Visit an AssetNode.

Parameters

  • translator (HTMLTranslator)

  • node (AssetNode) – The node being visited.

depart_asset_node(translator, node)[source]

Depart an AssetNode.

Parameters

  • translator (HTMLTranslator)

  • node (AssetNode) – The node being visited.

setup(app)[source]

Setup sphinx_toolbox.assets.

New in version 1.0.0.

Parameters

app (Sphinx) – The Sphinx application.

Return type

SphinxExtMetadata