Merge branch '6.0' into rohnsha0-control-panel

Author: stevepiercy

.readthedocs.yaml

@@ -18,7 +18,7 @@ build:
     # If there are no changes (git diff exits with 0) we force the command to return with 183.
     # This is a special exit code on Read the Docs that will cancel the build immediately.
     - |
-      if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/6.0 -- docs/ .readthedocs.yaml requirements-initial.txt requirements.txt;
+      if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/6.0 -- docs/ Makefile .readthedocs.yaml requirements-initial.txt requirements.txt;
       then
         exit 183;
       fi

Makefile

@@ -35,157 +35,166 @@ distclean: clean ## Clean docs build directory, Python virtual environment, and
 	rm docs/plone.api
 	rm docs/plone.restapi
 	rm docs/volto
-	@echo
 	@echo "Cleaned docs build directory, Python virtual environment, and symlinks."
+	@echo
 
 venv/bin/python:  ## Setup up Python virtual environment and install requirements
 	python3 -m venv venv
 	venv/bin/pip install -r requirements-initial.txt
 	venv/bin/pip install -r requirements.txt
-	@echo
 	@echo "Installation of requirements completed."
+	@echo
 
 docs/plone.api:  ## Setup plone.api docs
 	git submodule init
 	git submodule update
-	venv/bin/pip install -e submodules/plone.api/"[test]"
 	ln -s ../submodules/plone.api/docs ./docs/plone.api
-	@echo
 	@echo "Documentation of plone.api initialized."
+	@echo
+
+venv/plone.api-install: docs/plone.api
+	touch venv/plone.api-install
+	venv/bin/pip install plone.api -c submodules/plone.api/constraints.txt
+	venv/bin/pip install --no-deps -e submodules/plone.api/"[test]"
+	@echo "plone.api installed."
+	@echo
 
 docs/plone.restapi:  ## Setup plone.restapi docs
 	git submodule init
 	git submodule update
 	ln -s ../submodules/plone.restapi ./docs/plone.restapi
-	@echo
 	@echo "Documentation of plone.restapi initialized."
+	@echo
 
 docs/volto:  ## Setup Volto docs
 	git submodule init
 	git submodule update
 	ln -s ../submodules/volto/docs/source ./docs/volto
-	@echo
 	@echo "Documentation of volto initialized."
+	@echo
 
 .PHONY: deps
-deps: venv/bin/python docs/volto docs/plone.restapi docs/plone.api  ## Create Python virtual environment, install requirements, initialize or update the volto, plone.restapi, and plone.api submodules, and finally create symlinks to the source files.
-
+deps: venv/bin/python docs/volto docs/plone.restapi venv/plone.api-install  ## Create Python virtual environment, install requirements, initialize or update the volto, plone.restapi, and plone.api submodules, create symlinks to the source files, and finally install plone.api.
 
 .PHONY: html
 html: deps  ## Build html
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+	@echo
 
 .PHONY: manual
 manual: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b html -t manual . $(BUILDDIR)/manual
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/manual."
+	@echo
 
 .PHONY: dirhtml
 dirhtml: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+	@echo
 
 .PHONY: singlehtml
 singlehtml: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
-	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+	@echo
 
 .PHONY: pickle
 pickle: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
 	@echo "Build finished; now you can process the pickle files."
+	@echo
 
 .PHONY: json
 json: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
 	@echo "Build finished; now you can process the JSON files."
+	@echo
 
 .PHONY: htmlhelp
 htmlhelp: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
-	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+	@echo
 
 .PHONY: epub
 epub: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
-	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+	@echo
 
 .PHONY: latex
 latex: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
 	      "(use \`make latexpdf' here to do that automatically)."
+	@echo
 
 .PHONY: latexpdf
 latexpdf: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through pdflatex..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+	@echo
 
 .PHONY: text
 text: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
-	@echo
 	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+	@echo
 
 .PHONY: man
 man: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
-	@echo
 	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+	@echo
 
 .PHONY: texinfo
 texinfo: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo
 	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
 	@echo "Run \`make' in that directory to run these through makeinfo" \
 	      "(use \`make info' here to do that automatically)."
+	@echo
 
 .PHONY: info
 info: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo "Running Texinfo files through makeinfo..."
 	make -C $(BUILDDIR)/texinfo info
 	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+	@echo
 
 .PHONY: changes
 changes: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-	@echo
 	@echo "The overview file is in $(BUILDDIR)/changes."
+	@echo
 
 .PHONY: linkcheck
 linkcheck: deps  ## Run linkcheck
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
-	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 		"or in $(BUILDDIR)/linkcheck/ ."
+	@echo
 
 .PHONY: linkcheckbroken
 linkcheckbroken: deps  ## Run linkcheck and show only broken links
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck | GREP_COLORS='0;31' grep -wi "broken\|redirect" --color=always | GREP_COLORS='0;31' grep -vi "https://github.com/plone/volto/issues/" --color=always && if test $$? = 0; then exit 1; fi || test $$? = 1
-	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 		"or in $(BUILDDIR)/linkcheck/ ."
+	@echo
 
 .PHONY: vale
 vale: deps  ## Run Vale style, grammar, and spell checks
 	venv/bin/vale sync
 	venv/bin/vale --no-wrap $(VALEOPTS) $(VALEFILES)
-	@echo
 	@echo "Vale is finished; look for any errors in the above output."
+	@echo
 
 .PHONY: html_meta
 html_meta: deps  ## Add meta data headers to all Markdown pages
@@ -196,6 +205,7 @@ doctest: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."
+	@echo
 
 .PHONY: test
 test: clean linkcheckbroken  ## Clean docs build, then run linkcheckbroken
@@ -219,7 +229,8 @@ rtd-pr-preview:  ## Build pull request preview on Read the Docs
 	pip install -r requirements.txt
 	git submodule init
 	git submodule update
-	pip install -e submodules/plone.api[test]
+	pip install plone.api -c submodules/plone.api/constraints.txt
+	pip install --no-deps -e submodules/plone.api[test]
 	ln -s ../submodules/volto/docs/source ./docs/volto
 	ln -s ../submodules/plone.restapi ./docs/plone.restapi
 	ln -s ../submodules/plone.api/docs ./docs/plone.api

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
@@ -116,8 +117,6 @@
 linkcheck_anchors = True
 linkcheck_timeout = 5
 linkcheck_retries = 1
-# See https://github.com/plone/documentation/issues/1815
-linkcheck_report_timeouts_as_broken = False
 
 # The suffix of source filenames.
 source_suffix = {
@@ -140,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.
@@ -303,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 = {
@@ -323,6 +322,7 @@
     "fawrench": '<span class="fa fa-wrench" style="font-size: 1.6em;"></span>',
     "SUPPORTED_PYTHON_VERSIONS_PLONE60": "3.9, 3.10, 3.11, 3.12, or 3.13",
     "SUPPORTED_PYTHON_VERSIONS_PLONE61": "3.10, 3.11, 3.12, or 3.13",
+    "SUPPORTED_PYTHON_VERSIONS_PLONE62": "3.10, 3.11, 3.12, or 3.13",
 }
 
 
@@ -406,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