Sphinx plugin for VHS¶

Sphinx-VHS is an integration plugin for Sphinx and VHS, a tool by charm that renders terminal commands into GIFs. It allows referencing .tape files form your docs, and rendering them during sphinx build.

Quickstart¶

Install the sphinx-vhs package:
```
$ pip install sphinx-vhs
```
And add it to your conf.py:
```
extensions = ["sphinx_vhs", ...]
```
Now put some tapes into your documentation source dir, and use the vhs directive to render them:
```
.. vhs:: /_tapes/simple.tape
   :alt: A gif showing some hello-world text being typed into console.
```
Example output

Oh, and don’t forget to compile with SPHINXOPTS="-j auto" to speed things up. Sphinx-VHS can process tapes in parallel, but only if you let it.

Usage¶

.. vhs:: <path>¶

The vhs directive has all the same attributes as the figure, so you can caption it and reference it. Path is relative to the current doc file; if it starts with /, it is relative to the content root, just like with the figure directive.

Example:

.. vhs:: /_tapes/simple.tape
   :alt: A gif showing some hello-world text being typed into console.
   :name: gif-reference

   Look, a small :ref:`gif <gif-reference>`! Isn't it cute?

.. vhs-inline::¶

There’s also vhs-inline, which lets you paste a small tape right into your documentation. It also works like a figure, but, well, you won’t be able to caption it:

.. vhs-inline::

   Type "pwd"
   Sleep 500ms
   Enter
   Sleep 500ms
   Type "ls -l"
   Sleep 500ms
   Enter
   Sleep 5s

Rendering SVGs¶

There’s a fork of VHS that supports rendering SVGs instead of GIFs. To set it up, add the following to your conf.py:

vhs_repo = "agentstation/vhs"
vhs_format = "svg"

Settings¶

Sphinx-VHS adds the following settings to conf.py:

vhs_min_version: bool¶

Minimum VHS version required to render types.

Default: "0.5.0".

vhs_max_version: bool¶

Maximum VHS version required to render types. Set to None to disable maximum version checking.

Default: "2.0.0".

vhs_cwd: bool¶

Working dir for VHS runs. Affects Source commands in tapes.

Default: documentation source dir.

vhs_auto_install: bool¶

Whether to install VHS in case it is missing or outdated.

Default: True.

vhs_auto_install_location: pathlib.Path | str¶

Path where VHS binaries should be installed to.

Default: see vhs.default_cache_path().

vhs_cleanup_delay: datetime.timedelta¶

Sphinx VHS will delete unused GIFs after this period.

Default: 1 day.

vhs_n_jobs: int¶: Number of parallel jobs that will be used to render tapes. Default is equal to whatever’s passed to -j flag.

vhs_n_jobs_read_the_docs: int¶: Number of parallel jobs that will be used to render tapes in Read The Docs runners. Default is 8.

vhs_repo: str¶: Repo to download VHS from.

vhs_format: str¶: Format for rendering tapes, default is "gif". Can be "gif", "mp4", "webm", or "svg" (see Rendering SVGs).

FAQ¶

Build fails with `No usable sandbox! Update your kernel…`

If you’re running your build in CI that doesn’t enable sandbox API within its containers, you can set environment variable VHS_NO_SANDBOX=true.