Merge pull request plone#1462 from plone/contrib-card-image

Add documentation to contributing for Graphviz, specifying the width …

Author: stevepiercy

docs/contributing/myst-reference.md

@@ -99,30 +99,69 @@ Use [Shimmer](http://example.com) for cleaner whiter teeth.
 Use [Shimmer](http://example.com) for cleaner whiter teeth.
 
 
-#### Images and figures
+### 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.
+(static-assets-label)=
 
-```html
-You can copy <img alt="Copy icon" src="../../_images/copy.svg" class="inline"> blocks.
-```
+#### Static assets
 
-Note that the HTML attribute `class` must be set to `inline` to render the image inline at `1rem`. 
+When the documentation is in a submodule, paths to static assets—including, images, figures, and videos—must resolve in both the main documentation and the submodule's documentation.
 
-The above syntax renders as shown below.
+Inside the `docs` directory, place static assets in the `/_static/` directory, and preferably inside a subdirectory named after the part or page of the documentation.
+For example, in the `volto` submodule, inside its `src/docs` directory, place an image at `/_static/user-manual/block-left-add-icon.png`.
+In your markup, use that same `docs`-root-relative path for the target, such as `/_static/user-manual/block-left-add-icon.png`.
+Don't use file-relative paths.
 
-> You can copy <img alt="Copy icon" src="/_static/copy.svg" class="inline"> blocks.
+Configuration in the `conf.py` files for the main documentation and its submodules handle the resolution of `docs`-root-relative paths for you.
 
-Images and figures should always include `alt` text.
+
+#### Width of media
+
+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.
+
+
+(enhance-images-label)=
+
+#### 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 +172,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 +184,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
@@ -182,7 +243,7 @@ Accessibility is part of the [Plone brand and identity](https://plone.org/access
 ```
 
 
-#### Video
+### 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.
 
@@ -194,24 +255,59 @@ 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.
+See {ref}`static-assets-label` for details.
 
-Example syntax is shown below.
+Example MyST syntax is shown below.
 
-````
+````md
 ```{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.
+Don't use file-relative paths.
 The above MyST markup renders as shown below.
 
 ```{video} /_static/user-manual/blocks/block-copy-cut.mp4
     :width: 100%
 ```
 
 
-#### Code block
+### 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.
 
@@ -251,7 +347,7 @@ print("my 1st line")
 print(f"my {a}nd line")
 ```
 
-#### Escape literal backticks inline
+### Escape literal backticks inline
 
 ```md
 This is MyST syntax for term ``{term}`React` ``
@@ -260,7 +356,7 @@ This is MyST syntax for term ``{term}`React` ``
 This is MyST syntax for term ``{term}`React` ``
 
 
-#### Glossary terms
+### Glossary terms
 
 Add a term to the {ref}`glossary-label`, located at {file}`/glossary.md`.
 

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.