sphinx-contrib / youtube

A Sphinx extension to embed videos from YouTube

sphinxcontrib.youtube

Overview

This module provides support for including YouTube, Vimeo and Peertube videos in Sphinx rst documents.

This module defines directives, youtube, vimeo and peertube which insert videos from the respective platforms. They take a single, required argument, which is the video ID:

..  youtube:: dQw4w9WgXcQ

.. vimeo:: 148751763

.. peertube:: 327a21b3-374e-4373-8b2c-494c9f5e1f19

Custom Server for peertube instances:

.. peertube:: 327a21b3-374e-4373-8b2c-494c9f5e1f19

   :instance: peertube.tv

For full usage information, please see the web documentation.

youtube's Issues

Does not make parallel build support explicit

When doing a parallel build with sphinx-build -j auto ... I get

WARNING: the sphinxembeddedvideos.youtube extension does not declare if it is safe for parallel reading,
assuming it isn't - please ask the extension author to check and make it explicit

This is with sphinx 4.4. Does it support parallel builds? See also https://www.sphinx-doc.org/en/master/extdev/index.html?highlight=parallel_read_safe#extension-metadata.

Video thumbnail missing in PDF

Hey, is there any way to display thumbnails in the PDF output of a sphinx project?

We were using this format of adding YouTube videos: https://docs.beagleboard.org/latest/intro/contribution/rst-cheat-sheet.html#youtube-videos

But now we want to switch from that bulky format to the sleek format sphinxcontrib-youtube provides. I am willing to work on this improvement but bit new to all this, if possible please share some material to help with the development.

Pypi release of 1.3.0

currently very old 1.2.0 can be found on pypi as the latest.
Please release the latest to pypi.

And thanks by the way for the very helpful project

Generate QR codes for PDF outputs

Generating QR codes in the EPUB and LATEX builders would be good for printing out PDF/EPUB documents.

Wrapping text around around the video?

Thanks for this excellent tool!

Is there a way to make text wrap around the embedded video? One sided wrapping is all I need, i.e. if the video is aligned right or left.

Thanks again.

1.2.0 fails with "image not found"

Thanks a lot for this neat addon!

With 1.2.0, our docs would fails with

sphinx.errors.ExtensionError: Handler <function download_images at 0x7f4bf7164830> for event 'env-updated' threw an exception (exception: [Errno 2] No such file or directory: '/home/docs/checkouts/readthedocs.org/user_builds/zfit/checkouts/412/docs/_video_thumbnail/nGzyXVXfHnw.jpg')

where nGzyXVXfHnw is the youtube video code in the directive as

..  youtube:: nGzyXVXfHnw
       :width: 320

The whole build and failure can be found here.

With 1.1 it works

Please provide a LICENSE file

According to setup.py, license='BSD'.

However a LICENSE file is required.

... BSD ... special cases ... technically each one is a custom license, because each one has its own copyright line ...

Videos should not be embeded in EPUB files

Hi,

Thank you for the extension.
I am from pgAdmin4 team and we're creating docs with output as - HTML, EPUB and PDF. With this extension, HTML uses embedded and PDF shows links as expected. But, EPUB shows embedded which I think is not correct as EPUB is used for offline viewing. It should show a link just like PDF.
If I may raise a PR, are you willing to accept it to fix this?

Thanks.

Support twitch

It should be possible to support twitch as well?
If you can give me a couple of hints/guidance, I can open a PR to add the functionality.

RFE: Replace use of `pkg_resources` with `importlib.metadata`

See discussions:
astropy/astropy#11091
pypa/pip#7413
pypa/setuptools#3279

[tkloczko@devel-g2v youtube-1.2.0]$ grep -r pkg_resources
sphinxcontrib/__init__.py:__import__('pkg_resources').declare_namespace(__name__)
build/lib/sphinxcontrib/__init__.py:__import__('pkg_resources').declare_namespace(__name__)

New release

It would be nice to have a new release as I just hit #40 as well.

No module named 'urlparse'

Fresh pip install in conda environment:

Exception occurred:
  File "/home/ggarrett/miniconda3/envs/tudat-blog/lib/python3.8/site-packages/sphinxcontrib/youtube/youtube.py", line 3, in <module>
    import urlparse
ModuleNotFoundError: No module named 'urlparse'
The full traceback has been saved in /tmp/sphinx-err-8jj48cne.log, if you want to report the issue to the developers.

Dependency missing?

Trying to use it. But how to install it properly?

I am new to Sphinx. I want to use this with my Sphinx document. I've tried adding all these into my conf.py:

import os
import sys
#sys.path.insert(0, os.path.abspath('.'))
#sys.path.insert(0, os.path.abspath('./youtube-1.1.0'))
#sys.path.append(os.path.abspath('youtube-1.1.0'))
#sys.path.append(os.path.abspath('youtube'))
sys.path.append(os.path.abspath('sphinxcontrib'))
extensions = ['youtube']

But I am getting "ERROR: Unknown directive type "youtube" ".

Any help you can offer w/ how I should do the setup would be appreciated. Thanks.

pdf : thumbnail print at the wrong place

Dear all,

I have cloned your repository.
I tried to generate the hml and pdf documents.

For the html documentation, everything is ok as per the .rst file.

• html

For the pdf file, the thumbnail is added at the next page

• pdf

no module named sphinx.utils.display

It seems the refactoring of Sphinx continues and other things are deprecated from time to time.

In the latest build of the pydata-sphinx-theme we saw the following error when building with Pythin 3.11: https://github.com/pydata/pydata-sphinx-theme/actions/runs/6225350542/job/16895589354?pr=1446

Extension error:
Could not import extension sphinxcontrib.youtube (exception: No module named 'sphinx.util.display')

Update PyPI?

Hi,

Are there any plans to update the package available on PyPi? The current one is from 2015.

Thanks

publish to pypi

Please publish the latest version to pypi and extending support for newer python versions

Options for more than one link on the same page overwrite each other.

For example if you have:

..  youtube:: dQw4w9WgXcQ
   :url_parameters: ?start=0

and

..  youtube:: dQw4w9WgXcQ
   :url_parameters: ?start=43

Both links will generate with ?start=43

Support YouTube privacy-enhanced mode

Hi, it'd be great to have support for privacy-enhanced mode for YouTube embedding. Implementation should be quite easy, i.e. replacing youtube.com with youtube-nocookie.com.

To use Privacy Enhanced Mode:

1. Change the domain for the embed URL in your HTML from https://www.youtube.com to https://www.youtube-nocookie.com.

https://support.google.com/youtube/answer/171780

Let me know your thoughts!

status_iterator alias is deprecated

During a local build I hit this warning today:

/opt/mambaforge/envs/mnedev/lib/python3.10/site-packages/sphinxcontrib/youtube/youtube.py:3: RemovedInSphinx80Warning: The alias 'sphinx.util.status_iterator' is deprecated, use 'sphinx.util.display.status_iterator' instead.

I'll open a quick PR

the position becomes absolute when setting the width

I want to have an video responsive to my page size (use size in percent instead of pixels) and I want to have it centered.

I naively did the following:

.. youtube:: niOUVE8N7wo
    :align: center
    :width: 80%

And by setting the width I've lost the center alignement:

No CI

Currently there are no tests. This really needs to be fixed...

support align parameter as for the Image directive

Before discovering this extention, I was using an adaptation of the following gist. It was supporting the align parameter the same way as the image directive and moving to this lib is making all my youtube directive crash.

Do you think you could add this parameter to the directive?

It seems that @LSinterbotix has already opened a PR in this sense, do you think it's sufficient or does it require extra work ?

:privacy_mode: has no effect

Using sphinxcontrib-youtube==1.2.0 and code like this:

.. youtube:: zMAc-UyO0NA
   :privacy_mode:

But the :privacy_mode: parameter does not seem to work, the generated URL is not using the privacy URL. The generated HTML is

<iframe allowfullscreen="true" src="https://www.youtube.com/embed/zMAc-UyO0NA" style="border: 0; height: 345px; width: 560px">
</iframe>

import error: version (read the docs)

Experiencing this issue:

importError: cannot import name 'version' from 'sphinxcontrib.youtube' (/home/docs/checkouts/readthedocs.org/user_builds/mrcpsych-uk/envs/latest/lib/python3.7/site-packages/sphinxcontrib/youtube/init.py)

I am using read the docs for my documentation.

https://github.com/justpsychiatry/Clinically-Oriented-Psychology/tree/main/docs/source

document installation

THe documentation doesn't explain how to install the lib which is not straight forward (sphinxcontrib.youtube)

Show youtube thumbnail on latex export

Currently, the plugin only show a URL link to the YouTube video.

It will be awesome if the plugin could show:

The Thumbnails, 
The title
the link URL

All centered and clickable.

use a thumbnail in the latex output

In the current build of sphinxcontrib.youtube, the videos are displayed in the latex output as a link to the video.

Checking on the web I realize that the thumbnail image can easily be acceced so instead of a link the latex output could be a figure with the youtube thumbnail, the title and the link as caption.

I'm happy to make a PR if you guys think it could be useful.

PS: I also check vimeo for the sake of it and it seems to work more or less the same way

Request: add configuration variable to block thumbnail downloading

Would you consider making the new v1.2.0 thumbnail downloading optional? It appears to be happening even when the build target is HTML, even though there do not appear to be any thumbnail references in the generated HTML.

I use your plug-in to generate course sites with hundreds of YouTube and Vimeo links in my reference material, so the downloading represents a huge overhead on any clean build. Branch 1.1.0 builds super-fast without this feature.

Support youtube playlist

Heya, would you support having a youtube-plist directive?

.. youtube-plist:: XYZ

The embedding HTML is essentially the same, but using the playlist shortcode like: https://www.youtube.com/embed/videoseries?list=XYZ

If yes, then I can probably make a PR

Support timestamping

It would be nice to support an option such as :timestamp: 12520 which appends ?t=12520 to the embed URL.