1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
|
Quickstart
==========
This section contains basic information about **sphinxcontrib.video** to get you started.
Installation
------------
Use ``pip`` to install **sphinxcontrib-video** in your environment:
.. code-block:: console
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:
.. code-block:: python
extensions = [
#[...]
"sphinxcontrib.video",
]
video directive
---------------
You can now add video directly in your documentation:
.. code-block:: rst
.. video:: _static/video.mp4
.. video:: _static/video.mp4
Options
-------
the video directive supports all the optional attributes from the html tag as summurazied in the following table:
.. csv-table:: Optional Attributes
:header: 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 <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:
.. code-block:: rst
.. video:: _static/video.mp4
:nocontrols:
:autoplay:
:playsinline:
:muted:
:loop:
:poster: _static/image.png
:width: 100%
.. video:: _static/video.mp4
:nocontrols:
:autoplay:
:playsinline:
:muted:
:loop:
:width: 100%
:poster: _static/image.png
And using the ``:class:`` parameter in combination with custom css, you can change the display of the html ``<video>`` tag:
.. code-block:: rst
.. video:: _static/video.mp4
:class: video-bordered
.. 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
--------------
The browser used by the user may not support the codec of the primary source set in the directive. The ``<video>`` tag offers the possibility to add multiple sources, the first one compatible being the one displayed on screen. To use this options simply add the alternative source as a second argument to your video:
.. code-block:: rst
.. video:: _static/video.webm _static/video.mp4
.. video:: _static/video.webm _static/video.mp4
.. note::
to enforce this behavior set the sphinx parameter ``video_enforce_extra_source`` to ``True`` in your conf.py, it will then raise a warning when a secondary source is missing.
.. code-block:: python
# conf.py
video_enforce_extra_source = True
|
