Quickstart#

This section contains basic information about sphinxcontrib.video to get you started.

Installation#

Use pip to install sphinxcontrib-video in your environment:

pip install sphinxcontrib-video

Extension setup#

Enable the extension#

After installing sphinxcontrib-video, add sphinxcontrib.video to the list of extensions in your conf.py file:

extensions = [
    #[...]
    "sphinxcontrib.video",
]

video directive#

You can now add video directly in your documentation:

.. video:: _static/video.mp4

Options#

the video directive supports all the optional attributes from the html tag as summurazied in the following table:

Optional Attributes#
Attribute	value	Description
`:alt:`	`str`	Specify the text to write when the video cannot be displayed
`: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).
`:controlslist:`	`str`	Specifies the controls to show on the media element. Can only be one or more of comma separated values from `['nodownload', 'nofullscreen', 'noremoteplayback']`
`: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
`: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
`: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
`: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. It will be disabled when ‘caption’ is not set.

They can be used as any directive option:

.. video:: _static/video.mp4
    :nocontrols:
    :autoplay:
    :playsinline:
    :muted:
    :loop:
    :poster: _static/image.png
    :width: 100%

And using the :class: parameter in combination with custom css, you can change the display of the html <video> tag:

.. video:: _static/video.mp4
    :class: video-bordered

Alignment:

.. video:: _static/video.mp4
    :align: left

.. video:: _static/video.mp4
    :align: center

.. 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:

.. video:: _static/video.mp4
    :align: default

Caption:

.. video:: _static/video.mp4
    :align: center
    :caption: The caption text

The caption text

Use figwidth to set the maximum width of the caption text if the video is narrow:

.. 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