Add documentation to contributing for Graphviz, specifying the width of media, and use cards to enhance the display of images.

Author: stevepiercy

docs/contributing/myst-reference.md

@@ -102,27 +102,54 @@ Use [Shimmer](http://example.com) for cleaner whiter teeth.
 #### Images and figures
 
 [Figures](https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure) allow a caption and legend, whereas [images](https://docutils.sourceforge.io/docs/ref/rst/directives.html#images) do not.
+However we can {ref}`enhance images with cards <enhance-images-label>` to add a caption and more features.
 
 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.
-```
+##### Width of media
 
-Note that the HTML attribute `class` must be set to `inline` to render the image inline at `1rem`. 
+The main content area of a page in the documentation is 743 pixels wide.
+When taking screenshots or videos, resize your browser window, or try to limit the width of your media to 740 pixels.
+This will preserve legibility of images.
 
-The above syntax renders as shown below.
 
-> You can copy <img alt="Copy icon" src="/_static/copy.svg" class="inline"> blocks.
+(enhance-images-label)=
 
-Images and figures should always include `alt` text.
+##### Enhance images
+
+We use cards from the Sphinx extension [`sphinx-design`](https://sphinx-design.readthedocs.io/en/latest/cards.html) to enhance the display and functionality of images.
+
+Cards allow the display of a caption, create a link to the source image to display when it is too large to fit within the documentation page without scaling, and add a border to demarcate the image from the page's white background.
+
+The following MyST example will display as shown below.
+
+`````md
+````{card}
+```{image} /_static/caching/caching-disabled.png
+:alt: Caching Control Panel
+:target: /_static/caching/caching-disabled.png
+```
++++
+_Caching Control Panel_
+````
+`````
+
+````{card}
+```{image} /_static/caching/caching-disabled.png
+:alt: Caching Control Panel
+:target: /_static/caching/caching-disabled.png
+```
++++
+_Caching Control Panel_
+````
+
+
+##### Accessibility with `alt` text
 
 From [Web Accessibility In Mind (WebAIM)](https://webaim.org/techniques/alttext/):
 
@@ -133,6 +160,8 @@ From [Web Accessibility In Mind (WebAIM)](https://webaim.org/techniques/alttext/
 
 Accessibility is part of the [Plone brand and identity](https://plone.org/accessibility).
 
+The following MyST example will display as shown below.
+
 ````md
 ```{image} /_static/standards.png
 :alt: XKCD "Standards" comic strip
@@ -143,6 +172,26 @@ Accessibility is part of the [Plone brand and identity](https://plone.org/access
 :alt: XKCD "Standards" comic strip
 ```
 
+
+##### Inline images
+
+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="/_static/copy.svg" class="inline"> blocks.
+
+Images and figures should always include `alt` text.
+
+The following MyST example will display as shown below.
+
 ````md
 ```{eval-rst}
 .. figure:: /_static/voting_flowchart.png
@@ -195,9 +244,9 @@ It is helpful to include overlays of key strokes, and mouse and other input gest
 
 Paths to videos must resolve in both the main documentation and the submodule's documentation, if present.
 
-Example syntax is shown below.
+Example MyST syntax is shown below.
 
-````
+````md
 ```{video} /_static/user-manual/blocks/block-copy-cut.mp4
     :width: 100%
 ```
@@ -211,6 +260,39 @@ The above MyST markup renders as shown below.
 ```
 
 
+#### 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.
+
+The following MyST example will display as shown below.
+
+````markdown
+```{eval-rst}
+.. graphviz::
+    :align: center
+
+    digraph viewstructure {
+      {
+        node [margin=5,shape=box]
+      }
+      ZCML -> {Python, Template};
+    }
+```
+````
+
+```{eval-rst}
+.. graphviz::
+    :align: center
+
+    digraph viewstructure {
+      {
+        node [margin=5,shape=box]
+      }
+      ZCML -> {Python, Template};
+    }
+```
+
+
 #### Code block
 
 A Python code snippet without reStructuredText options, using a simple fence.

docs/contributing/sphinx-extensions.md

@@ -13,6 +13,7 @@ myst:
 
 We use several Sphinx extensions to enhance the presentation of Plone documentation.
 
+-   [`sphinx.ext.graphviz`](https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html) allows you to embed [Graphviz](https://graphviz.org/download/) graphs in your documents.
 -   [`sphinx.ext.intersphinx`](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html) provides linking between separate projects that use Sphinx for documentation.
 -   [`sphinx.ext.todo`](https://www.sphinx-doc.org/en/master/usage/extensions/todo.html) adds support for todo items.
 -   [`sphinx_copybutton`](https://sphinx-copybutton.readthedocs.io/en/latest/index.html)  adds a little "copy" button to the right of code blocks.