From af8bb8c2842176267931949f611c9c5999f01472 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Fri, 24 Jan 2025 01:07:35 +0100 Subject: [PATCH] Add `oEmbedPy` and `sphinxcontrib-youtube` for embedding videos ... from YouTube, Vimeo, and more. --- CHANGES.rst | 4 +++ docs/myst/notebook-text.md | 10 ++++++ docs/myst/notebook-traditional.ipynb | 15 +++++++++ docs/myst/video.md | 41 +++++++++++++++++++++++++ docs/rst/video.rst | 46 ++++++++++++++++++++++++++++ setup.py | 2 ++ src/crate/theme/rtd/conf/__init__.py | 2 ++ 7 files changed, 120 insertions(+) create mode 100644 docs/myst/video.md create mode 100644 docs/rst/video.rst diff --git a/CHANGES.rst b/CHANGES.rst index 6ba08bf9..8dae42a2 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -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 ----------------- diff --git a/docs/myst/notebook-text.md b/docs/myst/notebook-text.md index bd39d79a..5c1c8f37 100644 --- a/docs/myst/notebook-text.md +++ b/docs/myst/notebook-text.md @@ -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 diff --git a/docs/myst/notebook-traditional.ipynb b/docs/myst/notebook-traditional.ipynb index 016b5214..3b609b6a 100644 --- a/docs/myst/notebook-traditional.ipynb +++ b/docs/myst/notebook-traditional.ipynb @@ -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": { diff --git a/docs/myst/video.md b/docs/myst/video.md new file mode 100644 index 00000000..71e76f29 --- /dev/null +++ b/docs/myst/video.md @@ -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 `` HTML markup, just written down +into the Markdown file. Voilà. + + + +## 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/ diff --git a/docs/rst/video.rst b/docs/rst/video.rst new file mode 100644 index 00000000..7263a1e3 --- /dev/null +++ b/docs/rst/video.rst @@ -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 ```` HTML markup, just written down +into the Markdown file. Voilà. + +.. raw:: html + + + +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/ diff --git a/setup.py b/setup.py index d8adf909..4a5d2bfd 100644 --- a/setup.py +++ b/setup.py @@ -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", @@ -74,6 +75,7 @@ "sphinxext.opengraph>=0.4,<1", "sphinxcontrib-mermaid<2", "sphinxcontrib-plantuml>=0.21,<1", + "sphinxcontrib-youtube<2", ], python_requires=">=3.9", ) diff --git a/src/crate/theme/rtd/conf/__init__.py b/src/crate/theme/rtd/conf/__init__.py index f3965954..6d5e422f 100644 --- a/src/crate/theme/rtd/conf/__init__.py +++ b/src/crate/theme/rtd/conf/__init__.py @@ -34,6 +34,7 @@ extensions = [ "myst_nb", + "oembedpy.ext.sphinx", "sphinx_copybutton", "sphinx_design", "sphinx_design_elements", @@ -47,6 +48,7 @@ "sphinx.ext.graphviz", "sphinxcontrib.mermaid", "sphinxcontrib.plantuml", + "sphinxcontrib.youtube", "sphinxext.opengraph", ]