feat: add sphinx-contrib.video and sphinx-contrib.youtube supports

docs/conf.py

@@ -28,6 +28,8 @@
     "numpydoc",
     "sphinx_sitemap",
     "sphinxcontrib.mermaid",
+    "sphinxcontrib.video",
+    "sphinxcontrib.youtube",
     "sphinx_click",
     "sphinx_sqlalchemy",
 ]

docs/writing/media.rst

@@ -30,11 +30,11 @@ A simple image with ``image`` directive:
    .. code-block:: none
       :class: demo-code
 
-      .. image:: https://source.unsplash.com/daily?dog
+      .. image:: /_static/images/cat.jpg
 
    .. container:: demo-result
 
-      .. image:: https://source.unsplash.com/daily?dog
+      .. image:: /_static/images/cat.jpg
 
 
 align image
@@ -44,12 +44,12 @@ With ``:align:`` option, you can make the image float to left or right:
 
 .. code-block:: ReST
 
-    .. image:: https://source.unsplash.com/200x200/daily?cute+puppy
+    .. image:: /_static/icon-light.svg
       :align: left
       :height: 200
       :width: 200
 
-.. image:: https://source.unsplash.com/200x200/daily?cute+puppy
+.. image:: /_static/icon-light.svg
    :align: left
    :height: 200
    :width: 200
@@ -63,7 +63,7 @@ Lorem ipsum dolor sit amet consectetur adipisicing elit. Blanditiis
 sapiente veritatis doloribus accusantium molestiae modi recusandae
 excepturi facere, corrupti expedita sit.
 
-.. image:: https://source.unsplash.com/200x200/daily?cute+puppy
+.. image:: /_static/icon-light.svg
    :align: right
    :height: 200
    :width: 200
@@ -92,21 +92,19 @@ if ``figure`` directive will be converted to ``<figcaption>``.
       :caption: Image with a caption
       :class: demo-code
 
-      .. figure:: https://source.unsplash.com/daily?dog
+      .. figure:: /_static/images/dog.jpg
          :width: 800
          :align: center
 
          This is the ``caption``, *it can* contain **other markups**.
-         The photo is generated by Unsplash_ API.
 
    .. container:: demo-result
 
-      .. figure:: https://source.unsplash.com/daily?dog
+      .. figure:: /_static/images/dog.jpg
          :width: 800
          :align: center
 
          This is the ``caption``, *it can* contain **other markups**.
-         The photo is generated by Unsplash_ API.
 
 Containers
 ~~~~~~~~~~
@@ -121,13 +119,13 @@ We offer several container classes to decorate images:
 
       .. container:: image-1
 
-          .. image:: https://source.unsplash.com/daily?dog
+          .. image:: /_static/images/cat.jpg
 
    .. container:: demo-result
 
       .. container:: image-1
 
-          .. image:: https://source.unsplash.com/daily?dog
+          .. image:: /_static/images/cat.jpg
 
 
 .. container:: demo
@@ -137,13 +135,13 @@ We offer several container classes to decorate images:
 
       .. container:: image-2
 
-          .. image:: https://source.unsplash.com/daily?dog
+          .. image:: /_static/images/cat.jpg
 
    .. container:: demo-result
 
       .. container:: image-2
 
-          .. image:: https://source.unsplash.com/daily?dog
+          .. image:: /_static/images/cat.jpg
 
 Light and Dark
 --------------
@@ -158,26 +156,112 @@ example below, it will show a dog in light mode and a cat in dark mode.
       :caption: light and dark mode images
       :class: demo-code
 
-      .. figure:: https://source.unsplash.com/daily?dog
+      .. figure:: /_static/images/cat.jpg
          :figclass: light-only
          :width: 800
          :align: center
 
-      .. figure:: https://source.unsplash.com/daily?cat
+      .. figure:: /_static/images/dog.jpg
          :figclass: dark-only
          :width: 800
          :align: center
 
    .. container:: demo-result
 
-      .. figure:: https://source.unsplash.com/daily?dog
+      .. figure:: /_static/images/cat.jpg
          :figclass: light-only
          :width: 800
          :align: center
 
-      .. figure:: https://source.unsplash.com/daily?cat
+      .. figure:: /_static/images/dog.jpg
          :figclass: dark-only
          :width: 800
          :align: center
 
-.. _Unsplash: https://unsplash.com
+Videos
+------
+
+There is no built-in ``video`` directive for Sphinx. But you can use these extensions instead:
+
+- `sphinxcontrib-video <https://sphinxcontrib-video.readthedocs.io/>`_
+- `sphinxcontrib-youtube <https://sphinxcontrib-youtube.readthedocs.io/>`_
+
+Video
+~~~~~
+
+Here is an example of ``video`` directive:
+
+.. container:: demo
+
+   .. code-block:: none
+      :class: demo-code
+
+      .. video:: https://sphinxcontrib-video.readthedocs.io/en/latest/_images/video.mp4
+
+   .. container:: demo-result
+
+      .. video:: https://sphinxcontrib-video.readthedocs.io/en/latest/_images/video.mp4
+
+YouTube
+~~~~~~~
+
+Here is an example of ``youtube`` directive:
+
+.. container:: demo
+
+   .. code-block:: none
+      :class: demo-code
+
+      .. youtube:: j2BdNDTlWbo
+         :width: 100%
+
+   .. container:: demo-result
+
+      .. youtube:: j2BdNDTlWbo
+         :width: 100%
+
+Containers
+~~~~~~~~~~
+
+We offer several container classes to decorate videos:
+
+.. code-block:: ReST
+
+    .. container:: video-1
+
+      .. youtube:: j2BdNDTlWbo
+          :width: 100%
+
+    .. container:: video-1
+
+      .. video:: https://sphinxcontrib-video.readthedocs.io/en/latest/_images/video.mp4
+
+.. container:: video-1
+
+  .. youtube:: j2BdNDTlWbo
+      :width: 100%
+
+.. container:: video-1
+
+  .. video:: https://sphinxcontrib-video.readthedocs.io/en/latest/_images/video.mp4
+
+
+.. code-block:: ReST
+
+    .. container:: video-2
+
+      .. youtube:: j2BdNDTlWbo
+          :width: 100%
+
+    .. container:: video-2
+
+      .. video:: https://sphinxcontrib-video.readthedocs.io/en/latest/_images/video.mp4
+
+.. container:: video-2
+
+  .. youtube:: j2BdNDTlWbo
+      :width: 100%
+
+.. container:: video-2
+
+  .. video:: https://sphinxcontrib-video.readthedocs.io/en/latest/_images/video.mp4

requirements.txt

@@ -6,6 +6,8 @@ sphinx_sqlalchemy
 ipykernel
 jupyter-sphinx
 sphinx-togglebutton
+sphinxcontrib-video
+sphinxcontrib-youtube
 sphinxcontrib-mermaid
 sphinx-docsearch
 sphinx-click

static/css/components/container.css

@@ -12,7 +12,8 @@
   padding: 1rem;
 }
 
-.container.image-1 {
+.container.image-1,
+.container.video-1 {
   border: 0.5rem solid var(--accent-a3);
   border-radius: 6px;
 }
@@ -22,13 +23,22 @@
   margin: 0;
 }
 
-.container.image-2 {
+.container.video-1 video,
+.container.video-1 iframe {
+  border-radius: 4px;
+  width: 100%;
+  margin: 0;
+}
+
+.container.image-2,
+.container.video-2 {
   border: 1px solid var(--sy-c-border);
   padding: 1rem;
   border-radius: 6px;
 }
 
-.container.image-2 > img {
+.container.image-2 > img,
+.container.video-2 > video {
   margin: 0;
 }