Skip to content

Commit 9f2e065

Browse files
ericholscherclaude
andauthored
Docs: drop sphinxcontrib-video (#13251)
Our docs build is currently failing: ``` docs/user/addons.rst:101: WARNING: unknown node type: <dropdown_main: <dropdown_title...><container...>> docs/user/addons.rst:101: WARNING: unknown node type: <dropdown_title: <inline...><inline...>> ``` The dropdown isn't the problem — the **epub** builder is (we build `epub` with `fail_on_warning: true`), and the trigger is #13225, which moved us from our fork of `sphinxcontrib-video` to upstream 0.4.2. Sphinx transplants custom node visitors onto a translator by looking them up by builder *name* first, falling back to the builder *format* only when nothing was registered under the name ([`sphinx/registry.py`](https://github.com/sphinx-doc/sphinx/blob/v8.2.3/sphinx/registry.py#L423-L431)): ```python handlers = self.translation_handlers.get(builder.name, None) # 'epub' if handlers is None: handlers = self.translation_handlers.get(builder.format, {}) # 'html' ``` The epub builder normally has nothing registered under `epub`, so it inherits every extension's `html` handlers. Upstream 0.4.2 added `epub=(visit_video_node_unsuported, None)` to its `add_node()` call (our fork had no epub entry). That one registration makes the name lookup succeed, so the `html` fallback never runs and the epub translator ends up knowing *only* `video_node` — sphinx-design's dropdowns become unknown nodes and the build dies. I first wrote a `conf.py` workaround that dropped the `epub` key to restore the fallback, but the extension turned out to have exactly one call site in the entire docs tree — a single screencast on the Science page — so removing it seemed better than carrying a third-party extension plus a monkeypatch for one video. `raw:: html` is already used heavily in that same file, and the rendered `<video>` markup is equivalent to what the extension emitted. Worth a second look: - The mp4 stays where it was, on the `anti-pattern-sphinx-video-downloader` project. This PR doesn't change how the file is hosted. - Losing the extension means no graceful degradation for non-HTML builders. In practice that only affected latex/man/texinfo, which we don't build, and its epub behaviour was to warn and skip — which would have failed `fail_on_warning` anyway once the dropdown crash was out of the way. - This reopens #9489 in spirit (the fork is gone, but so is the dependency). Happy to go back to the workaround instead if we want to keep `.. video::` available for future use. Verified by building `docs/` with the pinned requirements: the reported warnings reproduce exactly on `main`, and both `html` and `epub` build clean with `-W` after this change, with the `<video>` element present in both outputs. `requirements/docs.txt` was recompiled without `--upgrade`, so no other pins moved. Closes the build breakage from #13225. --- _Generated by [Claude Code](https://claude.ai/code/session_01Kq5hTeCe1JedqHAF1UEGvt)_ Co-authored-by: Claude <noreply@anthropic.com>
1 parent e785797 commit 9f2e065

4 files changed

Lines changed: 8 additions & 7 deletions

File tree

docs/conf.py

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,6 @@
3232
"sphinx.ext.extlinks",
3333
"sphinx.ext.intersphinx",
3434
"sphinxcontrib.httpdomain",
35-
"sphinxcontrib.video",
3635
"sphinxemoji.sphinxemoji",
3736
"sphinxext.opengraph",
3837
]

docs/user/science.rst

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,8 +72,14 @@ Here's a brief overview of some :doc:`features </reference/features>` that peopl
7272

7373
Build and publish your project for every change made through Git (GitHub, GitLab, Bitbucket etc). Preview changes via pull requests. Receive notifications when something is wrong. How does this work? Have a look at this video:
7474

75-
.. video:: https://anti-pattern-sphinx-video-downloader.readthedocs.io/_static/videos/enable-pull-request-builders.mp4
76-
:height: 300
75+
.. raw:: html
76+
77+
<video controls height="300" preload="auto">
78+
<source
79+
src="https://anti-pattern-sphinx-video-downloader.readthedocs.io/_static/videos/enable-pull-request-builders.mp4"
80+
type="video/mp4"
81+
>
82+
</video>
7783

7884
.. dropdown:: 💬 Collaboration and community
7985

requirements/docs.in

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,4 +27,3 @@ sphinx-copybutton
2727
# Markdown
2828
myst_parser
2929

30-
sphinxcontrib-video

requirements/docs.txt

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -116,7 +116,6 @@ sphinx==8.2.3
116116
# sphinx-tabs
117117
# sphinxcontrib-httpdomain
118118
# sphinxcontrib-jquery
119-
# sphinxcontrib-video
120119
# sphinxemoji
121120
# sphinxext-opengraph
122121
sphinx-autobuild==2025.8.25
@@ -153,8 +152,6 @@ sphinxcontrib-qthelp==2.0.0
153152
# via sphinx
154153
sphinxcontrib-serializinghtml==2.0.0
155154
# via sphinx
156-
sphinxcontrib-video==0.4.2
157-
# via -r requirements/docs.in
158155
sphinxemoji==0.3.2
159156
# via -r requirements/docs.in
160157
sphinxext-opengraph==0.13.0

0 commit comments

Comments
 (0)