Add sections for MyST extension html_image and videos

Author: stevepiercy

docs/conf.py

@@ -52,12 +52,12 @@
     "sphinx_sitemap",
     "sphinxcontrib.httpdomain",  # plone.restapi
     "sphinxcontrib.httpexample",  # plone.restapi
+    "sphinxcontrib.video",
     "sphinxext.opengraph",
     "sphinx.ext.viewcode",  # plone.api
     "sphinx.ext.autosummary",  # plone.api
     "sphinx.ext.graphviz",
     "notfound.extension",
-    "sphinxcontrib.video",
 ]
 
 graphviz_output_format = "svg"
@@ -155,7 +155,7 @@
     #  instead of ```.
     "substitution",  # plone.restapi \
     # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#substitutions-with-jinja2
-    "html_image",
+    "html_image",  # For inline images. See https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
 ]
 
 myst_substitutions = {

docs/contributing/myst-reference.md

@@ -107,6 +107,21 @@ Use `image` for anything but diagrams.
 
 Use `figure` for diagrams.
 
+Paths to images and figures must resolve in both the main documentation and the submodule's documentation, if present.
+
+For inline images, we use the MyST extension [`html_image`](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#html-images).
+Example syntax is shown below.
+
+```html
+You can copy <img alt="Copy icon" src="../../_images/copy.svg" class="inline"> blocks.
+```
+
+Note that the HTML attribute `class` must be set to `inline` to render the image inline at `1rem`. 
+
+The above syntax renders as shown below.
+
+> You can copy <img alt="Copy icon" src="../../_images/copy.svg" class="inline"> blocks.
+
 Images and figures should always include `alt` text.
 
 From [Web Accessibility In Mind (WebAIM)](https://webaim.org/techniques/alttext/):
@@ -167,6 +182,35 @@ Accessibility is part of the [Plone brand and identity](https://plone.org/access
 ```
 
 
+#### Video
+
+To embed local videos, such as recordings of demonstrating the user interface, we require that the videos be saved as `.mp4` for greatest compatibility, usability, accessibility, and reduced file size.
+
+Avoid animated GIFs because they do not allow control of playback.
+
+Audio is not required, but may be helpful.
+If you include audio, it is helpful to include closed captions or a transcript.
+
+It is helpful to include overlays of key strokes, and mouse and other input gestures, to describe how to interact with the user interface.
+
+Paths to videos must resolve in both the main documentation and the submodule's documentation, if present.
+
+Example syntax is shown below.
+
+````
+```{video} /_static/user-manual/blocks/block-copy-cut.mp4
+    :width: 100%
+```
+````
+
+Note that the path must be absolute to support both submodules and the main documentation.
+The above MyST markup renders as shown below.
+
+```{video} /_static/user-manual/blocks/block-copy-cut.mp4
+    :width: 100%
+```
+
+
 #### Code block
 
 A Python code snippet without reStructuredText options, using a simple fence.

docs/contributing/sphinx-extensions.md

@@ -23,6 +23,7 @@ We use several Sphinx extensions to enhance the presentation of Plone documentat
 -   [`sphinxcontrib.httpexample`](https://sphinxcontrib-httpexample.readthedocs.io/en/latest/) enhances `sphinxcontrib-httpdomain` by generating RESTful HTTP API call examples for different tools from a single HTTP request example.
     Supported tools include [curl](https://curl.se/), [wget](https://www.gnu.org/software/wget/), [httpie](https://httpie.io/), and [python-requests](https://requests.readthedocs.io/en/latest/).
     It is used by Plone's {doc}`plone.restapi/docs/source/index`.
+-   [`sphinxcontrib.video`](https://pypi.org/project/sphinxcontrib-video/) allows you to embed local videos as defined by the HTML5 standard.
 -   [`sphinxext.opengraph`](https://pypi.org/project/sphinxext-opengraph/) generates [OpenGraph metadata](https://ogp.me/).
 -   [`sphinx.ext.viewcode`](https://www.sphinx-doc.org/en/master/usage/extensions/viewcode.html) generates pages of source code modules and links between the source and the description.
     It is used by {doc}`/plone.api/index`.