Sphinx YouTube Extension

Common errors

• Sphinx error: unknown extension: 'youtube'

  cause The extension name was incorrectly specified in `conf.py`.
  fix Change `extensions = ['youtube']` to `extensions = ['sphinxcontrib.youtube']` in your `conf.py` file.

• ERROR: Could not find a version that satisfies the requirement sphinxcontrib-youtube (from versions: none)
  ERROR: No matching distribution found for sphinxcontrib-youtube

  cause Typo in the package name during `pip install` or PyPI is unreachable.
  fix Verify the package name: `pip install sphinxcontrib-youtube`. Ensure your internet connection is active.

• TypeError: unsupported operand type(s) for +: 'NoneType' and 'str'

  cause This error or similar Python syntax errors can occur if you are running a `sphinxcontrib-youtube` version that uses newer Python features (e.g., f-strings) on an older Python environment (like Python 3.5).
  fix Upgrade your Python environment to 3.6 or newer. Refer to the `deprecated` warning regarding Python 3.5 support.

• Video does not appear in the generated HTML/PDF output.

  cause This can be due to an incorrect or malformed video URL, network issues preventing thumbnail download for LaTeX, or JavaScript blockers in the browser for HTML.
  fix 1. Check the video URL for correctness (must be full `https://` URL). 2. Inspect your browser's developer console for JavaScript errors. 3. Ensure your build environment has network access if generating LaTeX/PDF output.

Warnings

• gotcha When adding the extension to `conf.py`, ensure you use the full dotted name `sphinxcontrib.youtube`, not just `youtube`.
  Fix: In `conf.py`, change `extensions = ['youtube']` to `extensions = ['sphinxcontrib.youtube']`.
• deprecated Python 3.5 is no longer supported. Version 1.0.1 was released specifically to support Python 3.5 by removing f-strings, but subsequent versions have moved to maintain compatibility with actively supported Python versions (typically Python 3.6+).
  Fix: Upgrade your Python environment to 3.6 or newer. If stuck on Python 3.5, you might be limited to `sphinxcontrib-youtube==1.0.1` and older Sphinx versions.
• gotcha When building LaTeX output, `sphinxcontrib-youtube` downloads video thumbnails. This process requires network access and can increase build times. If your build environment is offline or has strict network policies, LaTeX builds might fail or be significantly slower.
  Fix: Ensure your build environment has network access during LaTeX builds. If building offline, consider disabling LaTeX output or checking `sphinxcontrib-youtube`'s configuration options for thumbnail handling (though direct options for this might be limited, it downloads them by default if targeting LaTeX).
• gotcha Video URLs must be complete, including the `http://` or `https://` scheme. Relative paths or IDs without a full URL scheme may not render correctly.
  Fix: Always provide the full, absolute URL to the video, e.g., `https://www.youtube.com/watch?v=dQw4w9WgXcQ`.

Install

• pip install sphinxcontrib-youtube Install latest version

Imports

• sphinxcontrib.youtube
  wrong:

  extensions = ['youtube']

  correct:

  extensions = ['sphinxcontrib.youtube']

  Sphinx extensions in the `sphinxcontrib` namespace must be referenced with their full dotted path in `conf.py`.

Quickstart

To enable `sphinxcontrib-youtube`, add `'sphinxcontrib.youtube'` to the `extensions` list in your Sphinx project's `conf.py` file. Then, use the `.. youtube::` directive in your reStructuredText or MyST files, providing the full URL to the video.

# conf.py

import os
import sys

project = 'My Sphinx Project'
copyright = '2023, Your Name'

extensions = [
    'sphinxcontrib.youtube',
]

# html_theme = 'alabaster' # Or any other Sphinx theme

# In your .rst or .md file (e.g., index.rst):
#
# .. youtube:: https://www.youtube.com/watch?v=dQw4w9WgXcQ
#    :width: 560
#    :height: 315
#    :align: center
#    :alt: Example YouTube Video
#
# For Vimeo or PeerTube, use their respective full URLs.
# .. youtube:: https://vimeo.com/209761509
#    :width: 560
#    :height: 315