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
Download
:download:`hello_world.txt <../assets/hello_world.txt>`
Configuration¶
API Reference¶
Functions:
|
Adds a link to an asset. |
|
Visit an |
|
Depart an |
|
Setup |
Classes:
|
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
) – Thedocutils.parsers.rst.states.Inliner
object that calledsource_role()
. It contains the several attributes useful for error reporting and document tree access.options (
Dict
) – A dictionary of directive options for customization (from therole
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 therole
directive). To be interpreted by the function. Default[]
.
- Return type
- 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