Docs: Add Sphinx directive for youtube embeds #3394
Conversation
Add a simple directive `.. youtube`, implemented as a local sphinx extension, that takes one argument — either: - A YouTube video ID (e.g. `aqz-KE-bpKQ`) - A YouTube URL (e.g. `https://www.youtube.com/watch?v=aqz-KE-bpKQ`) In either case, when generating HTML docs the directive will be replaced with an HTML embed of the video content. Valid forms for the URL include at least: - https://www.youtube.com/watch?v=YOUTUBE_ID - https://www.youtube.com/embed/YOUTUBE_ID - https://youtu.be/YOUTUBE_ID Features like start time (`?t=45`) are currently not supported.
|
Huh. Turns out (not at all surprisingly), someone had already written such a thing. Almost 10 years ago. sphinx-contrib: youtube extension It offers more configurability for how the video is embedded (controlling the width/height, etc.) buuuut unlike my version it doesn't allow you to enter a video URL, you have to extract just the ID. It's also so ancient that it uses HTTP URLs, which wouldn't be acceptable since the rest of the guide is served over HTTPS and we'd end up triggering the browser's insecure-page-element blocking. So, guess we should stick with mine. |
|
Oh, I'm way behind the times. The updated codebase lives here on GitHub as sphinx-contrib/youtube, and sports all the expected bells and whistles. |
|
Merging this as it won't affect anything unless we use it. (And if we end up switching over to the version from the official extensions collection, we can just delete this one from the |
Add a simple directive
.. youtube, implemented as a local sphinx extension, that takes one argument:aqz-KE-bpKQ)https://www.youtube.com/watch?v=aqz-KE-bpKQ)When generating HTML docs, any of these will be replaced with an embedded video player showing "Big Buck Bunny":
Advanced customization features like start time (
?t=45) are currently not supported.