Commit 9f2e065
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
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
32 | 32 | | |
33 | 33 | | |
34 | 34 | | |
35 | | - | |
36 | 35 | | |
37 | 36 | | |
38 | 37 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
72 | 72 | | |
73 | 73 | | |
74 | 74 | | |
75 | | - | |
76 | | - | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
77 | 83 | | |
78 | 84 | | |
79 | 85 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
27 | 27 | | |
28 | 28 | | |
29 | 29 | | |
30 | | - | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
116 | 116 | | |
117 | 117 | | |
118 | 118 | | |
119 | | - | |
120 | 119 | | |
121 | 120 | | |
122 | 121 | | |
| |||
153 | 152 | | |
154 | 153 | | |
155 | 154 | | |
156 | | - | |
157 | | - | |
158 | 155 | | |
159 | 156 | | |
160 | 157 | | |
| |||
0 commit comments