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:
pip3 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.
:scale: 25%
This will make you a nice gif:
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
The vhs directive has all the same attributes as the figure, so you can caption it and reference it:
.. _gif-reference:
.. vhs:: _tapes/simple.tape
:alt: A gif showing some hello-world text being typed into console.
:scale: 25%
Look, a small :ref:`gif <gif-reference>`! Isn't it cute?
This will make you a figure with a caption:
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::
:scale: 25%
Type "pwd"
Sleep 500ms
Enter
Sleep 500ms
Type "ls -l"
Sleep 500ms
Enter
Sleep 5s
Settings
Sphinx-VHS adds the following settings to conf.py
:
vhs_min_version
: minimum VHS version required to render types.Default:
"0.5.0"
.vhs_cwd
: working dir for VHS runs.Default: documentation source dir.
vhs_auto_install
: whether to install VHS in case it is missing or outdated.Default:
True
.vhs_auto_install_location
: path where VHS binaries should be installed to.Default: see
vhs.default_cache_path()
.
But can it run inside ReadTheDocs?
Nope! ReadTheDocs seems to use an older version of Linux core, which VHS can’t work with.
So, I’d recommend using GitHub Pages to host your documentation. Check out our workflow in .github/workflows/ci.yaml to see how you could set this up. Sorry for that 😕