Merge branch '6-dev' into plone.app.dexterity-init

jensens · web-flow · commit 2cc3305d5f91 · 2023-03-06T09:59:16.000+01:00
diff --git a/docs/conf.py b/docs/conf.py
@@ -322,7 +322,7 @@ def source_replace(app, docname, source):
 # Dict of replacements.
 source_replacements = {
     "{PLONE_BACKEND_MINOR_VERSION}": "6.0",
-    "{PLONE_BACKEND_PATCH_VERSION}": "6.0.1",
+    "{PLONE_BACKEND_PATCH_VERSION}": "6.0.2",
     "{NVM_VERSION}": "0.39.3",
 }
 
diff --git a/docs/contributing/authors.md b/docs/contributing/authors.md
@@ -228,7 +228,7 @@ This renders in the HTML `<head>` section as follows.
 <meta content="Plone, Documentation, SEO, meta, Vale, spell, grammar, style, check, linkcheck, lexer" name="keywords" />
 ```
 
-Additional {term}`Open Graph` metadata is implemented through the Sphinx extension [`sphinxext-opengraph`](https://github.com/wpilibsuite/sphinxext-opengraph) and the [MyST `html_meta` directive](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#setting-html-metadata), which resolves to the [Docutils `meta` directive](https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata).
+Additional {term}`Open Graph` metadata is implemented through the Sphinx extension [`sphinxext-opengraph`](https://github.com/wpilibsuite/sphinxext-opengraph) and the [MyST `html_meta` directive](https://myst-parser.readthedocs.io/en/latest/configuration.html#setting-html-metadata), which resolves to the [Docutils `meta` directive](https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata).
 See the site-wide configuration in {file}`conf.py`.
 
 
diff --git a/docs/contributing/myst-reference.md b/docs/contributing/myst-reference.md
@@ -39,10 +39,10 @@ Official MyST documentation
 ```
 
 
-### Targets and cross-referencing
+### Cross-references
 
 ```{seealso}
-[The MyST Syntax Guide > Targets and Cross-Referencing](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#targets-and-cross-referencing)
+[The MyST Syntax Guide > Cross-references](https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html)
 ```
 
 #### Link to a chapter or page
@@ -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`.
 
@@ -281,7 +377,7 @@ Using {term}`React` makes frontends fun again!
 
 ### Nesting directives
 
-You can [nest directives](https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html#nesting-directives), such as [admonitions](https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html#admonitions) and code blocks, by ensuring that the backtick-lines corresponding to the outermost directive are longer than the backtick-lines for the inner directives.
+You can [nest directives](https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html#nesting-directives), such as [admonitions](https://myst-parser.readthedocs.io/en/latest/syntax/admonitions.html) and code blocks, by ensuring that the backtick-lines corresponding to the outermost directive are longer than the backtick-lines for the inner directives.
 
 `````
 ````{tip}
diff --git a/docs/contributing/sphinx-extensions.md b/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.
diff --git a/docs/glossary.md b/docs/glossary.md
@@ -272,7 +272,7 @@ mrs-developer
     As a byproduct of its update operations, it also automatically adjusts `jsconfig.json`, which is used by Volto to configure webpack aliases.
 
 Yarn
-    [Yarn](https://classic.yarnpkg.com/) is a JavaScript package manager.
+    [Yarn](https://yarnpkg.com/) is a JavaScript package manager.
 
 Hydration
     After loading an HTML page generated with {term}`SSR` in the browser, React can populate the existing {term}`DOM` elements, and recreate and attach their coresponding components.
diff --git a/docs/install/install-from-packages.md b/docs/install/install-from-packages.md
@@ -145,21 +145,24 @@ npm install -g yo
 
 (install-prerequisites-yarn-label)=
 
-#### Yarn
+#### Yarn 3
 
-Install the Yarn Classic version (not the latest 2.x one) using `npm`.
+Install the latest Yarn 3 version (not the Classic 1.x one) using `npm`.
 
 1.  Open a terminal and type:
 
     ```shell
-    npm install yarn@1
+    npm install yarn@3
     ```
 
-2.  Verify that Yarn v1.x.x is installed and activated.
+2.  Verify that Yarn v3.x.x is installed and activated.
 
     ```shell
     yarn -v
     ```
+    ```console
+    3.2.3
+    ```
 
 
 (install-prerequisites-make-label)=
@@ -344,8 +347,6 @@ make start-frontend
 The Plone frontend server starts up and emits messages to the console.
 
 ```console
-yarn run v1.22.19
-$ razzle start
  WAIT  Compiling...
 
 
@@ -356,6 +357,7 @@ $ razzle start
   Compiled successfully in 9.62s
 
 ✅  Server-side HMR Enabled!
+sswp> Handling Hot Module Reloading
 Volto is running in SEAMLESS mode
 Using internal proxy: http://localhost:3000 -> http://localhost:8080/Plone
 🎭 Volto started at 0.0.0.0:3000 🚀
diff --git a/submodules/plone.restapi b/submodules/plone.restapi
@@ -1 +1 @@
-Subproject commit 2b0d7421864cb95a9471c96b629a826a42e96f46
+Subproject commit 11fdc5d2850503a81d093ae61a60d225e6cea977
diff --git a/submodules/volto b/submodules/volto
@@ -1 +1 @@
-Subproject commit e7cf0b141263b099091d64d1ba98751137c839e3
+Subproject commit c01a2ec71cba662a3999b22272c9c33138602804

Original file line number	Diff line number	Diff line change
`@@ -322,7 +322,7 @@ def source_replace(app, docname, source):`
`322`	`322`	`# Dict of replacements.`
`323`	`323`	`source_replacements = {`
`324`	`324`	`"{PLONE_BACKEND_MINOR_VERSION}": "6.0",`
`325`		`- "{PLONE_BACKEND_PATCH_VERSION}": "6.0.1",`
	`325`	`+ "{PLONE_BACKEND_PATCH_VERSION}": "6.0.2",`
`326`	`326`	`"{NVM_VERSION}": "0.39.3",`
`327`	`327`	`}`
`328`	`328`