Various fixes for contributors and authors (#1782)

* Add compare-buildout-pip to conceptual-guides index * Add alt attributes to videos * Add support for sphinxcontrib-youtube * Fix typo
plone · Nov 19, 2024 · 7edc892 · 7edc892
1 parent 27c4998
commit 7edc892
Show file tree

Hide file tree

Showing 5 changed files with 23 additions and 2 deletions.
diff --git a/docs/conceptual-guides/index.md b/docs/conceptual-guides/index.md
@@ -16,6 +16,7 @@ This part of the documentation provides explanation of concepts to deepen and br
 :maxdepth: 2
 
 choose-user-interface
+compare-buildout-pip
 distributions
 package-management
 make-build-backend-walk-through

diff --git a/docs/conf.py b/docs/conf.py
@@ -62,6 +62,7 @@
     "sphinxcontrib.httpexample",  # plone.restapi
     "sphinxcontrib.mermaid",
     "sphinxcontrib.video",
+    "sphinxcontrib.youtube",
     "sphinxext.opengraph",
 ]
 

diff --git a/docs/contributing/documentation/myst-reference.md b/docs/contributing/documentation/myst-reference.md
@@ -202,7 +202,7 @@ The following MyST example for `figure` will display as shown below.
 ````
 
 
-### Video
+### Video - local
 
 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.
 
@@ -223,11 +223,29 @@ Example MyST syntax is shown below.
 `````{example}
 ````{only} not text
 ```{video} ../../volto/_static/user-manual/blocks/block-copy-cut.mp4
+:alt: Copy or cut a block in Volto
 ```
 ````
 `````
 
 
+### Video - remote
+
+You can embed a remotely hosted video from [YouTube](https://www.youtube.com/), [Vimeo](https://vimeo.com/), or [PeerTube](https://joinpeertube.org/).
+
+The following example shows how to embed a video from YouTube using privacy mode.
+You should use privacy mode so that visitors from the European Union don't get blocked.
+
+```{youtube} kHec4MXH8vo
+:privacy_mode:
+:width: 100%
+```
+
+```{seealso}
+For additional configuration options, see the usage documentation for [`sphinxcontrib-youtube`](https://sphinxcontrib-youtube.readthedocs.io/en/latest/usage.html).
+```
+
+
 ### Diagrams and graphs with Graphviz
 
 We use [Graphviz](https://graphviz.org/download/) and its Sphinx extension [`sphinx.ext.graphviz`](https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html) to render diagrams and graph visualizations.

diff --git a/docs/contributing/documentation/themes-and-extensions.md b/docs/contributing/documentation/themes-and-extensions.md
@@ -63,4 +63,5 @@ We use several MyST and Sphinx extensions to enhance the presentation of Plone d
     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.
+-   [`sphinxcontrib.youtube`](https://pypi.org/project/sphinxcontrib-video/) allows you to embed remotely hosted videos from [YouTube](https://www.youtube.com/), [Vimeo](https://vimeo.com/, or [PeerTube](https://joinpeertube.org/).
 -   [`sphinxext.opengraph`](https://pypi.org/project/sphinxext-opengraph/) generates [OpenGraph metadata](https://ogp.me/).
diff --git a/requirements.txt b/requirements.txt
@@ -1,4 +1,3 @@
-lesscpy
 linkify-it-py
 plone-sphinx-theme
 sphinx-autobuild
@@ -11,6 +10,7 @@ sphinx-sitemap
 sphinxcontrib.httpdomain  # plone.restapi
 sphinxcontrib.httpexample  # plone.restapi
 sphinxcontrib-video
+sphinxcontrib-youtube
 sphinxext-opengraph
 sphinxcontrib.mermaid
 vale