align and caption

docs/quickstart.rst

@@ -51,12 +51,15 @@ the video directive supports all the optional attributes from the html tag as su
     ``:autoplay:``,,Specifies that the video will start playing as soon as it is ready
     ``:nocontrols:``,,Specifies that video controls should not be displayed (such as a play/pause button etc).
     ``:height:``,``int``,Sets the height of the video player in pixels
-    ``:loop:``,,Specifies that the video will start over again, every time it is finished
+    ``:loop:``,,"Specifies that the video will start over again, every time it is finished"
     ``:muted:``,,Specifies that the audio output of the video should be muted
-    ``:poster:``,``str``, Specifies an image url to be shown while the video is downloading, or until the user hits the play button
+    ``:poster:``,``str``, "Specifies an image url to be shown while the video is downloading, or until the user hits the play button"
     ``:preload:``,``str``,"Specifies if and how the author thinks the video should be loaded when the page loads. Can only be values from ``['auto', 'metadata', 'none']``"
-    ``:width:``,``int``, Sets the width of the video player in pixels
+    ``:width:``,``int``, Sets the width of the video player in pixels or percentage
     ``:class:``,``str``, Set extra class to the video html tag
+    ``:align:``,``str``, "Sets the horizontal alignment. Can only be values from ``['default', 'left', 'center', 'right']``"
+    ``:caption:``,``str``, Set the caption text under video
+    ``:figwidth:``,``str``, Set the maximum width of caption text. It is defined as the same of 'figwidth' `in figure <https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure>`_. It will be disabled when 'caption' is not set.
 
 They can be used as any directive option:
 
@@ -83,6 +86,158 @@ And using the ``:class:`` parameter in combination with custom css, you can chan
 .. video:: _static/video.mp4
     :class: video-bordered
 
+Alignment: 
+
+.. code-block:: rst
+
+    .. video:: _static/video.mp4
+        :align: left
+
+.. video:: _static/video.mp4
+    :align: left
+
+.. code-block:: rst
+
+    .. video:: _static/video.mp4
+        :align: center
+
+.. video:: _static/video.mp4
+    :align: center
+
+.. code-block:: rst
+
+    .. video:: _static/video.mp4
+        :align: right
+
+.. video:: _static/video.mp4
+    :align: right
+
+For consistency with previous versions, which not support align, the default value of align 'left' when the it is not set.
+If you want to use the 'default' defined by theme, you need to, manually, set it to 'default':
+
+.. code-block:: rst
+
+    .. video:: _static/video.mp4
+        :align: default
+
+.. video:: _static/video.mp4
+    :align: default
+
+Caption:
+
+.. code-block:: rst
+
+    .. video:: _static/video.mp4
+        :align: center
+        :caption: The caption text
+
+.. video:: _static/video.mp4
+    :align: center
+    :caption: The caption text
+
+Use figwidth to set the maximum width of the caption text if the video is narrow:
+
+.. code-block:: rst
+
+    .. video:: _static/video.mp4
+        :width: 300
+        :figwidth: 60%
+        :align: center
+        :caption: The caption text text xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx
+
+.. video:: _static/video.mp4
+    :width: 300
+    :figwidth: 60%
+    :align: center
+    :caption: The caption text text xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx
+
+The width of video is not controlled by 'figwidth', you need to use 'width' to control it. For example, if you don't set the 'width', the following problems may occur: The video with is greater than 'figwith', resulting in results that are not aligned as expected.
+
+.. code-block:: rst
+
+    .. video:: _static/video.mp4
+        :figwidth: 60%
+        :align: center
+        :caption: The caption text text xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx
+
+.. video:: _static/video.mp4
+    :figwidth: 60%
+    :align: center
+    :caption: The caption text text xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx
+
+When the 'width' is set to a percentage, the percent number indicates the relative to 'figwidth':
+
+.. code-block:: rst
+
+    .. video:: _static/video.mp4
+        :width: 100%
+        :figwidth: 60%
+        :align: center
+        :caption: The caption text text xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx
+
+.. video:: _static/video.mp4
+    :width: 100%
+    :figwidth: 60%
+    :align: center
+    :caption: The caption text text xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx
+
+When 'caption' is set, and 'align' is 'left' or 'right', the video will be float to text in some themes.
+
+.. code-block:: rst
+
+    .. video:: _static/video.mp4
+        :width: 95%
+        :figwidth: 65%
+        :align: left
+        :caption: The caption text text xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx
+
+    long long text...
+
+.. video:: _static/video.mp4
+    :width: 95%
+    :figwidth: 65%
+    :align: left
+    :caption: The caption text text xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx
+
+long long text long long text long long text long long text long long text long long text long long text
+long long text long long text long long text long long text long long text long long text long long text
+long long text long long text long long text long long text long long text long long text long long text
+long long text long long text long long text long long text long long text long long text long long text
+long long text long long text long long text long long text long long text long long text long long text
+long long text long long text long long text long long text long long text long long text long long text
+long long text long long text long long text long long text long long text long long text long long text
+long long text long long text long long text long long text long long text long long text long long text
+long long text long long text long long text long long text long long text long long text long long text
+long long text long long text long long text long long text long long text long long text long long text
+
+.. code-block:: rst
+
+    .. video:: _static/video.mp4
+        :width: 95%
+        :figwidth: 65%
+        :align: right
+        :caption: The caption text text xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx
+
+    long long text...
+
+.. video:: _static/video.mp4
+    :width: 95%
+    :figwidth: 65%
+    :align: right
+    :caption: The caption text text xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx
+
+long long text long long text long long text long long text long long text long long text long long text
+long long text long long text long long text long long text long long text long long text long long text
+long long text long long text long long text long long text long long text long long text long long text
+long long text long long text long long text long long text long long text long long text long long text
+long long text long long text long long text long long text long long text long long text long long text
+long long text long long text long long text long long text long long text long long text long long text
+long long text long long text long long text long long text long long text long long text long long text
+long long text long long text long long text long long text long long text long long text long long text
+long long text long long text long long text long long text long long text long long text long long text
+long long text long long text long long text long long text long long text long long text long long text
+
+
 Advanced Usage
 --------------
 

sphinxcontrib/video.py

@@ -97,6 +97,9 @@ class Video(SphinxDirective):
         "preload": directives.unchanged,
         "width": directives.unchanged,
         "class": directives.unchanged,
+        "align": directives.unchanged,
+        "caption": directives.unchanged,
+        "figwidth": directives.unchanged,
     }
 
     def run(self) -> List[video_node]:
@@ -112,7 +115,7 @@ def run(self) -> List[video_node]:
             height = ""
 
         width: str = self.options.get("width", "")
-        if width and not width.isdigit():
+        if width and not (width.isdigit() or str_is_percentage(width)):
             logger.warning(
                 f'The provided width ("{width}") is ignored as it\'s not an integer'
             )
@@ -126,6 +129,18 @@ def run(self) -> List[video_node]:
             )
             preload = "auto"
 
+        align: str = self.options.get("align", "left")
+        if not (align in ["left", "center", "right", "default"]):
+            logger.warning(
+                f'The align type ("{align}") is not a supported. defaulting to "left"'
+            )
+            align = "left"
+
+        caption: str = self.options.get("caption", "")
+        figwidth: str = self.options.get("figwidth", "")
+        if not caption:
+            figwidth = ""
+
         # add the primary video files as images in the builder
         sources = [get_video(self.arguments[0], env)]
 
@@ -150,10 +165,25 @@ def run(self) -> List[video_node]:
                 preload=preload,
                 width=width,
                 klass=self.options.get("class", ""),
+                align=align,
+                caption=caption,
+                figwidth=figwidth,
             )
         ]
 
 
+def str_is_percentage(string: str) -> bool:
+    return string[-1] == "%" and str_is_float(string[0:-1])
+
+
+def str_is_float(string: str) -> bool:
+    try:
+        float(string)
+        return True
+    except ValueError:
+        return False
+
+
 class VideoPostTransform(SphinxPostTransform):
     """Ensure video files are copied to build directory.
 
@@ -184,11 +214,24 @@ def run(self):
 
 def visit_video_node_html(translator: HTMLTranslator, node: video_node) -> None:
     """Entry point of the html video node."""
+    html: str = ""
+    # has caption?
+    if node["caption"]:
+        html += '<figure '
+    else:
+        html += '<div '
+    # align
+    html += f' class="align-{node["align"]}"'
+    # figwidth
+    if node["figwidth"]:
+        html += f' style="width: {node["figwidth"]}"><div class="align-center">'
+    else:
+        html += '>'
     # start the video block
     attr: List[str] = [f'{k}="{node[k]}"' for k in SUPPORTED_OPTIONS if node[k]]
     if node["klass"]:  # klass need to be special cased
         attr += [f"class=\"{node['klass']}\""]
-    html: str = f"<video {' '.join(attr)}>"
+    html += f"<video {' '.join(attr)}>"
 
     # build the sources
     builder = translator.builder
@@ -210,7 +253,17 @@ def visit_video_node_html(translator: HTMLTranslator, node: video_node) -> None:
 
 def depart_video_node_html(translator: HTMLTranslator, node: video_node) -> None:
     """Exit of the html video node."""
-    translator.body.append("</video>")
+    html_caption: str = ""
+    if node["figwidth"]:
+        html_caption += "</div>"
+    if node["caption"]:
+        html_caption += ('<figcaption class="align-center">'
+                         '<p style="text-align: left; display:inline-block">'
+                         f'<span class="caption-text">{node["caption"]}</span>'
+                         '</p></figcaption></figure>')
+    else:
+       html_caption += '</div>'
+    translator.body.append(f"</video>{html_caption}")
 
 
 def visit_video_node_unsuported(translator: SphinxTranslator, node: video_node) -> None: