Merge branch '6.0' into makefile-combine-plone.api

Author: stevepiercy

.gitignore

@@ -11,5 +11,8 @@ docs/plone.api
 docs/plone.restapi
 docs/volto
 
+# created on first make command
+plone.api-install
+
 # editor files
 .vscode

docs/conf.py

@@ -58,6 +58,7 @@
     "sphinx_examples",
     "sphinx_reredirects",
     "sphinx_sitemap",
+    "sphinx_tippy",
     "sphinxcontrib.httpdomain",  # plone.restapi
     "sphinxcontrib.httpexample",  # plone.restapi
     "sphinxcontrib.mermaid",
@@ -102,7 +103,7 @@
     r"https://coveralls.io/repos/github/plone/plone.restapi/badge.svg\?branch=main",  # plone.restapi
     r"https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors#Identifying_the_issue",  # volto
     r"https://docs.cypress.io/guides/references/migration-guide#Migrating-to-Cypress-version-10-0",  # volto
-    r"https://browsersl.ist/#",
+    r"https://browsersl.ist/#",  # volto
     # Ignore unreliable sites
     r"https://web.archive.org/",
     r"https://www.gnu.org/",  # Consider removal when upgrading Sphinx
@@ -138,6 +139,7 @@
     "**/eggs",
     "_inc/.*",
     "plone.restapi/.*",
+    "plone.restapi/*.md",
     "plone.restapi/bin",
     "plone.restapi/develop-eggs",
     "plone.restapi/docs/source/glossary.md",  # There can be only one Glossary.
@@ -301,15 +303,14 @@
 # For more information see:
 # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
 myst_enable_extensions = [
-    "deflist",  # Support definition lists.
-    # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#definition-lists
-    "linkify",  # Identify "bare" web URLs and add hyperlinks.
-    "colon_fence",  # You can also use ::: delimiters to denote code fences,\
-    #  instead of ```.
-    "substitution",  # plone.restapi \
-    # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#substitutions-with-jinja2
+    "attrs_block", # Support parsing of block attributes.
+    "attrs_inline", # Support parsing of inline attributes.
+    "colon_fence",  # You can also use ::: delimiters to denote code fences, instead of ```.
+    "deflist",  # Support definition lists. https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#definition-lists
     "html_image",  # For inline images. See https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#html-images
+    "linkify",  # Identify "bare" web URLs and add hyperlinks.
     "strikethrough",  # See https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#syntax-strikethrough
+    "substitution",  # Use Jinja2 for substitutions. https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#substitutions-with-jinja2
 ]
 
 myst_substitutions = {
@@ -405,6 +406,16 @@
 sitemap_filename = "sitemap-custom.xml"
 
 
+# -- sphinx-tippy configuration ----------------------------------
+tippy_anchor_parent_selector = "article.bd-article"
+tippy_enable_doitips = False
+tippy_enable_wikitips = False
+tippy_props = {
+    "interactive": True,
+    "placement": "auto-end",
+}
+
+
 # -- Options for HTML help output -------------------------------------------------
 
 # Output file base name for HTML help builder.

docs/contributing/documentation/admins.md

@@ -103,7 +103,7 @@ The following are example files that you can use to configure your project for p
 
 -   [Plone Sphinx Theme `Makefile`](https://github.com/plone/plone-sphinx-theme/blob/main/Makefile), specifically the `rtd-pr-preview` section.
     This is the command to use to build documentation previews on Read the Docs.
--   [Plone Sphinx Theme `requirements-docs.txt`](https://github.com/plone/plone-sphinx-theme/blob/main/requirements-docs.txt) specifies the requirements to use Plone Sphinx Theme and build the docs.
+-   [Plone Sphinx Theme `pyproject.toml`](https://github.com/plone/plone-sphinx-theme/blob/main/pyproject.toml) specifies the requirements to use Plone Sphinx Theme and build the docs.
 -   [Plone Sphinx Theme `conf.py`](https://github.com/plone/plone-sphinx-theme/blob/main/docs/conf.py) the Sphinx configuration file to build the docs.
 -   [Plone Sphinx Theme `.readthedocs.yaml`](https://github.com/plone/plone-sphinx-theme/blob/main/.readthedocs.yaml) specifies the configuration and Makefile command that Read the Docs uses to build the docs.
 -   [Plone Sphinx Theme `.github/workflows/rtd-pr-preview.yml`](https://github.com/plone/plone-sphinx-theme/blob/main/.github/workflows/rtd-pr-preview.yml) specifies when to build the docs, specifically only when a pull request is opened and there are changes to the documentation files.

docs/contributing/documentation/index.md

@@ -175,7 +175,7 @@ git push
 ```
 
 ```{seealso}
-[How to undo a committed submodule command](https://stackoverflow.com/a/46500544/2214933).
+[How to undo a committed submodule command](https://stackoverflow.com/questions/46500441/how-to-undo-a-committed-submodule-command/46500544#46500544).
 ```
 
 

docs/contributing/documentation/myst-reference.md

@@ -415,6 +415,13 @@ This is MyST syntax for term ``{term}`React` ``
 ```
 
 
+### Strikethrough
+
+```{example}
+This is MyST markup for ~~strikethrough~~ inline text format.
+```
+
+
 ### Glossary terms
 
 Add a term to the {ref}`glossary-label`, located at {file}`/glossary.md`.

docs/contributing/documentation/themes-and-extensions.md

@@ -30,37 +30,41 @@ We use several MyST and Sphinx extensions to enhance the presentation of Plone d
 
 ### MyST
 
+-   [`attrs_block`](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#block-attributes) supports parsing of block attributes before certain block syntaxes.
+-   [`attrs_inline`](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#inline-attributes) supports parsing of inline attributes before certain inline syntaxes.
+-   [`colon_fence`](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#code-fences-using-colons) supports the use of three colons `:::` as delimiters to denote code fences, instead of three backticks `` ``` ``.
 -   [`deflist`](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#definition-lists) supports definition lists.
+-   [`html_image`](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#html-images) supports the use of HTML `<img>` tags.
 -   [`linkify`](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#linkify) identifies "bare" web URLs and adds hyperlinks.
--   [`colon_fence`](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#code-fences-using-colons) supports the use of three colons `:::` as delimiters to denote code fences, instead of three backticks `` ``` ``.
+-   [`strikethrough`](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#syntax-strikethrough) supports the use of strikethrough markup.
 -   [`substitution`](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#substitutions-with-jinja2) supports the use of substitutions with Jinja2.
--   [`html_image`](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#html-images) supports the use of HTML `<img>` tags.
 
 
 ### Sphinx
 
 -   [`myst_parser`](https://myst-parser.readthedocs.io/en/latest/) parses MyST, a rich and extensible flavour of Markdown for authoring documentation.
 -   [`sphinx-design`](https://sphinx-design.readthedocs.io/en/latest/), with a configuration name of `sphinx_design`, adds grids, cards, icons, badges, buttons, tabs, and dropdowns.
 -   [`sphinx-examples`](https://ebp-sphinx-examples.readthedocs.io/en/latest/) adds "example snippets" that allow you to show off source Markdown and the result of rendering it in Sphinx.
--   [`sphinx-notfound-page`](https://sphinx-notfound-page.readthedocs.io/en/latest/index.html), with a configuration name of `notfound.extension`, creates a custom 404 page and helps generate proper static resource links to render the page properly.
+-   [`sphinx-notfound-page`](https://sphinx-notfound-page.readthedocs.io/en/latest/index.html), with a configuration name of `notfound.extension`, creates a custom 404 page and helps generate proper static resource links to render the page.
+-   [`sphinx-tippy`](https://sphinx-tippy.readthedocs.io/en/latest/), with a configuration name of `sphinx_tippy`, provides hover tips in your documentation.
 -   [`sphinx.ext.autodoc`](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) pulls in documentation from Python docstrings to generate reStructuredText which in turn gets parsed by Sphinx and rendered to the output format.
-    It is used by {doc}`/plone.api/index`.
+    It's used by {doc}`/plone.api/index`.
 -   [`sphinx.ext.autosummary`](https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html) generates function/method/attribute summary lists.
-    It is used by {doc}`/plone.api/index`.
+    It's used by {doc}`/plone.api/index`.
 -   [`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.ifconfig`](https://www.sphinx-doc.org/en/master/usage/extensions/ifconfig.html) includes content based on configuration.
 -   [`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.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`.
+    It's used by {doc}`/plone.api/index`.
 -   [`sphinx_copybutton`](https://sphinx-copybutton.readthedocs.io/en/latest/index.html)  adds a little "copy" button to the right of code blocks.
 -   [`sphinx_reredirects`](https://documatt.com/sphinx-reredirects/) handles redirects for moved pages.
 -   [`sphinx_sitemap`](https://pypi.org/project/sphinx-sitemap/) generates multiversion and multilanguage [sitemaps.org](https://www.sitemaps.org/protocol.html) compliant sitemaps.
 -   [`sphinxcontrib.httpdomain`](https://sphinxcontrib-httpdomain.readthedocs.io/en/stable/) provides a Sphinx domain for describing HTTP APIs.
-    It is used by Plone's {doc}`/plone.restapi/docs/source/index`.
+    It's used by Plone's {doc}`/plone.restapi/docs/source/index`.
 -   [`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`.
+    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's used by Plone's {doc}`/plone.restapi/docs/source/index`.
 -   [`sphinxcontrib.mermaid`](https://pypi.org/project/sphinxcontrib-mermaid/) allows you to embed [Mermaid](https://mermaid.js.org/) graphs in your documents, including general flowcharts, sequence diagrams, and Gantt charts.
 -   [`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/).

docs/deployment/server-environment.md

@@ -15,7 +15,7 @@ This page in the deployment guide covers how to prepare a server environment for
 You will need to prepare your environment with the following items.
 
 ```{note}
-Should we reuse or update {ref}`install-packages-hardware-requirements-label`?
+Should we reuse or update {ref}`create-project-cookieplone-hardware-requirements-label`?
 ```
 
 -   server instance with an operating system that Plone can run on

docs/install/containers/images/backend.md

@@ -222,7 +222,7 @@ services:
 | `CORS_ALLOW_HEADERS` | A comma separated list of request headers allowed to be sent by the client, for example `X-My-Header` | `Accept,Authorization,Content-Type,X-Custom-Header` |
 | `CORS_MAX_AGE` | Indicates how long the results of a preflight request can be cached | `3600` |
 
-These variables are used to configure [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS).
+These variables are used to configure [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS).
 
 (containers-images-backend-add-ons-label)=
 

docs/install/containers/index.md

@@ -55,7 +55,7 @@ The system requirements include those required by Docker itself.
 -   [Windows](https://docs.docker.com/desktop/setup/install/windows-install/)
 
 Plone 6 itself requires memory and disk space in addition to those of Docker alone.
-See its {ref}`install-packages-hardware-requirements-label`.
+See its {ref}`create-project-cookieplone-hardware-requirements-label`.
 
 
 ### Install Docker

requirements.txt

@@ -7,6 +7,7 @@ sphinx-examples
 sphinx-notfound-page  # Documentation only
 sphinx-reredirects
 sphinx-sitemap
+sphinx-tippy
 sphinxcontrib.httpdomain  # plone.restapi
 sphinxcontrib.httpexample  # plone.restapi
 sphinxcontrib-video