Support installing VHS from different repos and building SVGs instead of GIFs

Author: taminomara

docs/source/conf.py

@@ -29,6 +29,8 @@
 }
 autodoc_member_order = "bysource"
 nitpick_ignore_regex = [(r"py:class", r".*\.T")]
+vhs_repo = "agentstation/vhs"
+vhs_format = "svg"
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

docs/source/index.rst

@@ -115,6 +115,20 @@ Usage
 .. _figure: https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure
 
 
+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``:
+
+__ https://github.com/agentstation/vhs/
+
+.. code-block:: python
+
+   vhs_repo = "agentstation/vhs"
+   vhs_format = "svg"
+
+
 Settings
 --------
 
@@ -175,6 +189,16 @@ Sphinx-VHS adds the following settings to ``conf.py``:
    Number of parallel jobs that will be used to render tapes in Read The Docs runners.
    Default is ``8``.
 
+.. py:data:: vhs_repo
+   :type: str
+
+   Repo
+
+.. py:data:: vhs_format
+   :type: str
+
+   Format for rendering tapes, default is ``"gif"``.
+
 
 FAQ
 ---

pyproject.toml

@@ -22,8 +22,8 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "sphinx>=8.0,<9.0",
-    "vhs>=1.0.0,<2.0",
+    "sphinx>=8.0,<10.0",
+    "vhs>=1.1.0,<2.0",
 ]
 
 [dependency-groups]

sphinx_vhs/__init__.py

@@ -17,6 +17,7 @@
 import sphinx.errors
 import sphinx.util.parallel
 import vhs
+from docutils.parsers.rst import directives
 from docutils.parsers.rst.directives.images import Figure
 from sphinx.transforms import SphinxTransform
 from sphinx.util import logging
@@ -51,6 +52,11 @@ def _get_used_files(
 
 
 class VhsDirective(SphinxDirective, Figure):
+    option_spec = {
+        **Figure.option_spec,  # type: ignore
+        "format": lambda x: directives.choice(x, ["gif", "svg"]),
+    }
+
     def run(self):
         lines = self._get_tape_contents_inlined()
         tape = "\n".join(lines)
@@ -66,8 +72,9 @@ def run(self):
         )
         dest_dir.mkdir(parents=True, exist_ok=True)
         dest_tape = dest_dir / ("vhs.tape")
-        dest_render = dest_dir / ("vhs.gif")
-        dest_file = dest_dir / (filename + ".gif")
+        format = self.options.get("format") or self.env.config["vhs_format"] or "gif"
+        dest_render = dest_dir / (f"vhs.{format}")
+        dest_file = dest_dir / (filename + f".{format}")
 
         with dest_tape.open("w") as file:
             file.write(tape)
@@ -290,6 +297,7 @@ def generate_vhs(
                 install=app.config["vhs_auto_install"],
                 cache_path=app.config["vhs_auto_install_location"],
                 env=environ,
+                repo=app.config["vhs_repo"],
             )
         except vhs.VhsError as e:
             raise sphinx.errors.ExtensionError(str(e)) from e
@@ -401,6 +409,8 @@ def setup(app: sphinx.application.Sphinx):
     app.add_config_value(
         "vhs_cleanup_delay", timedelta(days=1), rebuild="env", types=timedelta
     )
+    app.add_config_value("vhs_repo", "charmbracelet/vhs", rebuild="env")
+    app.add_config_value("vhs_format", "gif", rebuild="env")
 
     app.add_directive("vhs", VhsDirective)
     app.add_directive("vhs-inline", InlineVhsDirective)