Skip to content

Commit

Permalink
Add oEmbedPy and sphinxcontrib-youtube for embedding videos
Browse files Browse the repository at this point in the history
... from YouTube, Vimeo, and more.
  • Loading branch information
amotl committed Jan 24, 2025
1 parent 6dc0039 commit 270e0f5
Show file tree
Hide file tree
Showing 7 changed files with 120 additions and 0 deletions.
4 changes: 4 additions & 0 deletions CHANGES.rst
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,13 @@ Unreleased
- Added `JupySQL`_, for running SQL in Jupyter/IPython
- MyST-NB: Fixed dark mode for tables in Jupyter Notebooks.
Thank you, @surister and @msbt.
- Added `oEmbedPy`_ and `sphinxcontrib-youtube`_ for embedding
videos from YouTube, Vimeo, and more

.. _JupySQL: https://jupysql.ploomber.io/
.. _MyST-NB: https://myst-nb.readthedocs.io/
.. _oembedpy: https://oembedpy.readthedocs.io/
.. _sphinxcontrib-youtube: https://sphinxcontrib-youtube.readthedocs.io/

2024/12/13 0.37.2
-----------------
Expand Down
10 changes: 10 additions & 0 deletions docs/myst/notebook-text.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,16 @@ Rendering the result table has unfortunate output when using dark mode.
Please switch to light mode instead.
:::

## Video embeds

Sometimes it is needed for optimal information conveyance, or just for
entertainment purposes: Notebooks can have video embeds, too.

:::{youtube} YE7VzlLtp-4
:width: 480
:height: 320
:::


[CrateDB Examples: notebook/jupyter]: https://github.com/crate/cratedb-examples/tree/main/notebook/jupyter
[ipython-sql]: https://github.com/catherinedevlin/ipython-sql
Expand Down
15 changes: 15 additions & 0 deletions docs/myst/notebook-traditional.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -238,6 +238,21 @@
"\n",
"[CrateDB Examples: notebook/jupyter]: https://github.com/crate/cratedb-examples/tree/main/notebook/jupyter\n"
]
},
{
"metadata": {},
"cell_type": "markdown",
"source": [
"## Video embeds\n",
"\n",
"Sometimes it is needed for optimal information conveyance, or just for\n",
"entertainment purposes: Notebooks can have video embeds, too.\n",
"\n",
":::{youtube} YE7VzlLtp-4\n",
":width: 480\n",
":height: 320\n",
":::"
]
}
],
"metadata": {
Expand Down
41 changes: 41 additions & 0 deletions docs/myst/video.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Videos

Videos, for example from YouTube or Vimeo, can be embedded using inline
HTML, [sphinxcontrib-youtube], or [oembedpy].

## Inline HTML

This uses a basic `<iframe ...></iframe>` HTML markup, just written down
into the Markdown file. Voilà.

<iframe width="480" height="320" src="https://www.youtube-nocookie.com/embed/YE7VzlLtp-4" title="Big Buck Bunny" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>

## sphinxcontrib-youtube

This uses the `youtube` directive provided by `sphinxcontrib-youtube`.

:::{youtube} YE7VzlLtp-4
:width: 480
:height: 320
:::

## oembedpy

This uses the `oembed` directive provided by `oembedpy`.

:::{oembed} https://www.youtube.com/watch?v=YE7VzlLtp-4
:maxwidth: 480
:maxheight: 320
:::

:::{tip}
[oEmbedPy], as the name suggests, can render [oEmbed] information provided
by any HTML page, for example Bluesky, Reddit, Twitter/X, and many more.
Registered oEmbed providers can be explored per [providers.json].
:::


[oEmbed]: https://oembed.com/
[oembedpy]: https://oembedpy.readthedocs.io/
[providers.json]: https://oembed.com/providers.json
[sphinxcontrib-youtube]: https://sphinxcontrib-youtube.readthedocs.io/
46 changes: 46 additions & 0 deletions docs/rst/video.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
######
Videos
######

Videos, for example from YouTube or Vimeo, can be embedded using inline
HTML, `sphinxcontrib-youtube`_, or `oembedpy`_.

Inline HTML
===========

This uses a basic ``<iframe ...></iframe>`` HTML markup, just written down
into the Markdown file. Voilà.

.. raw:: html

<iframe width="480" height="320" src="https://www.youtube-nocookie.com/embed/YE7VzlLtp-4" title="Big Buck Bunny" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>

sphinxcontrib-youtube
=====================

This uses the ``youtube`` directive provided by ``sphinxcontrib-youtube``.

.. youtube:: YE7VzlLtp-4
:width: 480
:height: 320

oembedpy
========

This uses the ``oembed`` directive provided by ``oembedpy``.

.. oembed:: https://www.youtube.com/watch?v=YE7VzlLtp-4
:maxwidth: 480
:maxheight: 320

.. tip::

`oEmbedPy`_, as the name suggests, can render `oEmbed`_ information provided
by any HTML page, for example Bluesky, Reddit, Twitter/X, and many more.
Registered oEmbed providers can be explored per `providers.json`_.


.. _oEmbed: https://oembed.com/
.. _oembedpy: https://oembedpy.readthedocs.io/
.. _providers.json: https://oembed.com/providers.json
.. _sphinxcontrib-youtube: https://sphinxcontrib-youtube.readthedocs.io/
2 changes: 2 additions & 0 deletions setup.py
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,7 @@
"jupysql<0.11",
"myst-nb<1.2",
"myst-parser[linkify]<5",
"oembedpy<0.8",
"sphinx>=7.1,<9",
"sphinx-basic-ng==1.0.0b2",
"sphinx-copybutton>=0.3.1,<1",
Expand All @@ -74,6 +75,7 @@
"sphinxext.opengraph>=0.4,<1",
"sphinxcontrib-mermaid<2",
"sphinxcontrib-plantuml>=0.21,<1",
"sphinxcontrib-youtube<2",
],
python_requires=">=3.9",
)
2 changes: 2 additions & 0 deletions src/crate/theme/rtd/conf/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@

extensions = [
"myst_nb",
"oembedpy.ext.sphinx",
"sphinx_copybutton",
"sphinx_design",
"sphinx_design_elements",
Expand All @@ -47,6 +48,7 @@
"sphinx.ext.graphviz",
"sphinxcontrib.mermaid",
"sphinxcontrib.plantuml",
"sphinxcontrib.youtube",
"sphinxext.opengraph",
]

Expand Down

0 comments on commit 270e0f5

Please sign in to comment.