diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 4425568..40c925b 100644 --- a/docs/quickstart.rst +++ b/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 `_. 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 is set to `left` when nothing is set. +If you want to use the alignment defined by your 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 -------------- diff --git a/sphinxcontrib/video.py b/sphinxcontrib/video.py index c799b7d..7534a20 100644 --- a/sphinxcontrib/video.py +++ b/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 += '
' + 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"
" + if node["caption"]: + html_caption += ('
' + '

' + f'{node["caption"]}' + '

') + else: + html_caption += '' + translator.body.append(f"{html_caption}") def visit_video_node_unsuported(translator: SphinxTranslator, node: video_node) -> None: