Skip to content

Commit

Permalink
Merge branch 'berlin2123-patch-1'
Browse files Browse the repository at this point in the history
  • Loading branch information
@12rambau
12rambau committed Jan 3, 2025
2 parents ba36a5d + d4f9b39 commit 047758e
Show file tree
Hide file tree
Showing 2 changed files with 218 additions and 6 deletions.
161 changes: 158 additions & 3 deletions docs/quickstart.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,13 +51,16 @@ 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 (ignored if relative width is used)
``: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 or relative to the page's width if a percentage
``:class:``,``str``, Set extra class to the video html tag
``:playsinline:``,,Specifies that the video will play in-line (instead of full-screen) on small devices.
``: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:

Expand Down Expand Up @@ -91,6 +94,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
--------------

Expand Down
63 changes: 60 additions & 3 deletions sphinxcontrib/video/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,9 @@ class Video(SphinxDirective):
"width": directives.unchanged,
"class": directives.unchanged,
"playsinline": directives.flag,
"align": directives.unchanged,
"caption": directives.unchanged,
"figwidth": directives.unchanged,
}

def run(self) -> List[video_node]:
Expand All @@ -108,7 +111,7 @@ def run(self) -> List[video_node]:
# check options that need to be specific values

width: str = self.options.get("width", "")
if width and not (width.isdigit() or width[-1] == "%" and width[:-1].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 '
"or integer percentage"
Expand Down Expand Up @@ -138,6 +141,18 @@ def run(self) -> List[video_node]:
)
preload = "auto"

align: str = self.options.get("align", "left")
if align not 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)]

Expand All @@ -163,10 +178,27 @@ def run(self) -> List[video_node]:
width=width,
klass=self.options.get("class", ""),
playsinline="playsinline" in self.options,
align=align,
caption=caption,
figwidth=figwidth,
)
]


def str_is_percentage(string: str) -> bool:
"""Check if the string represent a valid percentage value."""
return string[-1] == "%" and str_is_float(string[0:-1])


def str_is_float(string: str) -> bool:
"""Check if the string represent a valid float value."""
try:
float(string)
return True
except ValueError:
return False


class VideoPostTransform(SphinxPostTransform):
"""Ensure video files are copied to build directory.
Expand Down Expand Up @@ -197,11 +229,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
Expand All @@ -223,7 +268,19 @@ 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:
Expand Down

0 comments on commit 047758e

Please sign in to comment.