Add documentation for how to administer Read the Docs for documentation and update Plone Sphinx Theme configuration (#1667)

* Add documentation for how to administer Read the Docs for documentation

* Remove subprojects mention

* Remove Netlify configuration

* Update requirements files

* Remove netlify.toml

* Add RTD configuration

* Update conf.py for new theme

* Add configuration for pull request previews on RTD

* Try using deps to pull in submodules and create symlinks

* RTD cannot run multiple make targets

* Remove obsolete Sphinx template `_templates/sections/header-article.html`

* Purge Netlify

* Fix link references

* Relocate static files

* Purge Netlify

* Clean up `conf.py`

* Fix link

* Revert "Try using deps to pull in submodules and create symlinks"

This reverts commit c23aa55.

* Rename headings and improve flow

* Rewrite search engine indexing section
Add Cancel builds programmatically section
Add Cancel builds on a branch section

* Update configuration to build only on changes to docs files

* Use commands instead

* - Sort items in .gitignore
- Remove obsolete documentation-custom.css file
- Merge `conf.py` with 6.0

* - Remove obsolete custom.css file

* Update comments in linkcheckignore

* plone.api must be installed to build its API docs. Remove symlinks in `distclean` allows its installation.

* Tidy up conf.py

* This file's content was migrated elsewhere

* Disable Edit this page, and add comments explaining that it does not support multiple repositories

* Update documentation for build pull request previews.

Author: stevepiercy

.gitignore

@@ -3,13 +3,13 @@
 
 # Generated files
 /_build
-/styles/Microsoft
 /share
+/styles/Microsoft
 
 # symlinked from submodule
-docs/volto
-docs/plone.restapi
 docs/plone.api
+docs/plone.restapi
+docs/volto
 
 # editor files
 .vscode

Makefile

@@ -30,8 +30,13 @@ clean:  ## Clean docs build directory
 	cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/
 
 .PHONY: distclean
-distclean: clean ## Clean docs build directory and Python virtual environment
+distclean: clean ## Clean docs build directory, Python virtual environment, and symlinks
 	rm -rf venv
+	rm docs/plone.api
+	rm docs/plone.restapi
+	rm docs/volto
+	@echo
+	@echo "Cleaned docs build directory, Python virtual environment, and symlinks."
 
 venv/bin/python:  ## Setup up Python virtual environment and install requirements
 	python3 -m venv venv
@@ -40,24 +45,24 @@ venv/bin/python:  ## Setup up Python virtual environment and install requirement
 	@echo
 	@echo "Installation of requirements completed."
 
-docs/plone.api:
-	git submodule init; \
-	git submodule update; \
-	venv/bin/pip install -e submodules/plone.api/"[test]"; \
+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."
 
-docs/plone.restapi:
-	git submodule init; \
-	git submodule update; \
+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."
 
-docs/volto:
-	git submodule init; \
-	git submodule update; \
+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."

docs/backend/upgrading/version-specific-migration/upgrade-to-60.md

@@ -168,7 +168,7 @@ The standard theme in Classic UI was updated to Bootstrap 5, CSS variables, and
 If you have a theme that builds on Barceloneta, you most likely need various changes.
 
 It may be best to start with a fresh theme, and try to keep the changes minimal.
-The training documentation lists {doc}`three possible theming strategies <theming_plone_5/index>`:
+The training documentation lists {doc}`three possible theming strategies <training-2022:theming_plone_5/index>`:
 
 -   Create a theme based on Barceloneta.
 -   Create a theme from scratch.

docs/conf.py

@@ -33,6 +33,7 @@
 # The full version, including alpha/beta/rc tags.
 release = "6"
 
+
 # -- General configuration ----------------------------------------------------
 
 # Add any paths that contain templates here, relative to this directory.
@@ -85,11 +86,14 @@
     # Ignore pages that require authentication
     r"https://github.com/orgs/plone/teams/",  # requires auth
     r"https://github.com/plone/documentation/issues/new",  # requires auth
+    r"https://github.com/plone/volto/issues/new/choose",  # requires auth
     r"https://opensource.org/",  # requires auth
     # Ignore github.com pages with anchors
     r"https://github.com/.*#.*",
     # Ignore github.com searches
     r"https://github.com/search",
+    # Ignore GitHub 429 Client Error: Too Many Requests for url
+    r"https://github.com/collective/plone.app.locales/commits/master/",
     # Ignore rate limiting by github.com
     r"https://github.com/plone/volto/issues",
     r"https://github.com/plone/volto/pull",
@@ -98,11 +102,8 @@
     r"https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors#Identifying_the_issue",
     r"https://docs.cypress.io/guides/references/migration-guide#Migrating-to-Cypress-version-10-0",  # volto
     # Ignore unreliable sites
-    # r"https://chromewebstore.google.com/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi",  # TODO retest with latest Sphinx when upgrading theme. chromewebstore recently changed its URL and has "too many redirects".
-    # r"https://chromewebstore.google.com/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd",  # TODO retest with latest Sphinx when upgrading theme. chromewebstore recently changed its URL and has "too many redirects".
-    # r"https://stackoverflow.com",  # volto and documentation  # TODO retest with latest Sphinx.
-    r"https://web.archive.org/",  # volto
-#    r"https://www.youtube.com/playlist",  # volto, TODO remove after installing sphinxcontrib.youtube
+    r"https://web.archive.org/",
+    r"https://www.youtube.com/playlist",  # volto, TODO remove after installing sphinxcontrib.youtube
     r"http://z3c.pt",  # fluke where Sphinx interprets this as a URL
 ]
 linkcheck_allowed_redirects = {  # TODO: Confirm usage of linkcheck_allowed_redirects
@@ -241,22 +242,23 @@
     "primary_sidebar_end": [
         "version-switcher",
     ],
-    "repository_branch": "main",
+    "repository_branch": "6.0",
     "repository_url": "https://github.com/plone/documentation",
     "search_bar_text": "Search",
     "switcher": {
         "json_url": "https://6.docs.plone.org/_static/switcher.json",
         "version_match": version,
     },
-    "use_edit_page_button": True,
+    "use_edit_page_button": False,  # This option does not support multiple repositories.
     "use_issues_button": True,
     "use_repository_button": True,
 }
 # suggest edit link
 # remark: {{ file_name }} is mandatory in "edit_page_url_template"
-html_context = {
-    "edit_page_url_template": "https://6.docs.plone.org/contributing/index.html?{{ file_name }}#making-contributions-on-github",
-}
+# used by `use_edit_page_button`, but it does not support multiple repositories
+# html_context = {
+#     "edit_page_url_template": "https://6.docs.plone.org/contributing/documentation/index.html?{{ file_name }}#making-contributions-on-github",
+# }
 
 # Announce that we have an opensearch plugin
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_use_opensearch
@@ -275,7 +277,6 @@
 html_extra_path = [
     "robots.txt",
 ]
-
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
@@ -295,16 +296,7 @@
 # Don't show class signature with the class' name.
 autodoc_class_signature = "separated"
 
-
-# -- Options for sphinx_sitemap to html -----------------------------
-
-# Used by sphinx_sitemap to generate a sitemap
-html_baseurl = "https://6.docs.plone.org/"
-# https://sphinx-sitemap.readthedocs.io/en/latest/advanced-configuration.html#customizing-the-url-scheme
-sitemap_url_scheme = "{link}"
-sitemap_filename = "sitemap-custom.xml"
-
-# -- Options for myST markdown conversion to html -----------------------------
+# -- Options for MyST markdown conversion to HTML -----------------------------
 
 # For more information see:
 # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
@@ -328,6 +320,7 @@
     "fawrench": '<span class="fa fa-wrench" style="font-size: 1.6em;"></span>',
 }
 
+
 # -- Intersphinx configuration ----------------------------------
 
 # This extension can generate automatic links to the documentation of objects
@@ -359,7 +352,7 @@
 
 
 # -- Mermaid configuration ----------------------------------
-# mermaid_version = "10.9.1"
+mermaid_version = "11.2.0"
 
 
 # -- OpenGraph configuration ----------------------------------
@@ -374,12 +367,13 @@
 ]
 
 
-# -- sphinx.ext.todo -----------------------
+# -- Options for sphinx.ext.todo -----------------------
+
 # See http://sphinx-doc.org/ext/todo.html#confval-todo_include_todos
 todo_include_todos = True
 
 
-# -- sphinx-notfound-page configuration ----------------------------------
+# -- Options for sphinx-notfound-page ----------------------------------
 
 notfound_urls_prefix = ""
 notfound_template = "404.html"
@@ -396,6 +390,15 @@
 }
 
 
+# -- Options for sphinx_sitemap to HTML -----------------------------
+
+# Used by sphinx_sitemap to generate a sitemap
+html_baseurl = "https://6.docs.plone.org/"
+# https://sphinx-sitemap.readthedocs.io/en/latest/advanced-configuration.html#customizing-the-url-scheme
+sitemap_url_scheme = "{link}"
+sitemap_filename = "sitemap-custom.xml"
+
+
 # -- Options for HTML help output -------------------------------------------------
 
 # Output file base name for HTML help builder.
@@ -411,7 +414,7 @@
         "index",
         "PloneDocumentation.tex",
         "Plone Documentation",
-        "The Plone community",
+        "Plone community",
         "manual",
     ),
 ]
@@ -421,6 +424,7 @@
 latex_logo = "_static/logo_2x.png"
 
 # --  Configuration for source_replacements extension -----------------------
+
 # An extension that allows replacements for code blocks that
 # are not supported in `rst_epilog` or other substitutions.
 # https://stackoverflow.com/a/56328457/2214933

docs/contributing/documentation/admins.md

@@ -96,11 +96,11 @@ 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-dev.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 `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 `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 command 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 against the `main` branch and there are changes to documentation files.
-    You might need to adjust the branch name, paths, and files to check for changes.
+-   [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.
+    You might need to adjust the `paths` and `project-slug` for your documentation.
 
 
 ### Import your project
@@ -113,9 +113,10 @@ After logging in to your Read the Docs account, you can import your project.
 1.  In the {guilabel}`Add project` screen, you can configure basic project settings, including its {guilabel}`Name`, {guilabel}`Repository URL`, {guilabel}`Default branch`, and {guilabel}`Language`.
     The defaults are usually accurate.
 1.  Click {guilabel}`Next`.
-1.  A sample `.readthedocs.yaml` file is suggested, if you have not already added one.
-1.  Click {guilabel}`Finish`.
-    Read the Docs will redirect you to the project details, and start building the docs.
+    Read the Docs will redirect you to the project details, and start building the docs, but you don't need to wait.
+1.  Click the {guilabel}`Settings` button.
+1.  Scroll to the end of the page and check the box for {guilabel}`Build pull requests for this project`.
+1.  Click {guilabel}`Save` to save the new setting.
 
 
 ### Search engine indexing
@@ -138,10 +139,10 @@ cp source-path/block-robots.txt docs-root-path/robots.txt
 ```
 
 ```{seealso}
+-   [`robots.txt` support](https://docs.readthedocs.io/en/stable/reference/robots.html)
 -   [Automation rules](https://docs.readthedocs.io/en/stable/automation-rules.html)
 -   [Versions](https://docs.readthedocs.io/en/stable/versions.html)
 -   [Managing versions automatically](https://docs.readthedocs.io/en/stable/guides/automation-rules.html)
--   [`robots.txt` support](https://docs.readthedocs.io/en/stable/reference/robots.html)
 ```
 
 

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

@@ -58,9 +58,9 @@ We use several MyST and Sphinx extensions to enhance the presentation of Plone d
 -   [`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 is 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`.
+    It is used by Plone's {doc}`/plone.restapi/docs/source/index`.
 -   [`sphinxcontrib.video`](https://pypi.org/project/sphinxcontrib-video/) allows you to embed local videos as defined by the HTML5 standard.
 -   [`sphinxext.opengraph`](https://pypi.org/project/sphinxext-opengraph/) generates [OpenGraph metadata](https://ogp.me/).

docs/contributing/index.md

@@ -167,7 +167,7 @@ Plone API
 
 Plone REST API
 :   A RESTful API for Plone.
-    See {doc}`plone.restapi/docs/source/contributing/index`.
+    See {doc}`/plone.restapi/docs/source/contributing/index`.
 
 Volto
 :   Plone 6 default frontend.

requirements-initial.txt

@@ -1,3 +1,4 @@
+# requirements-initial.txt
 # From https://dist.plone.org/release/6-latest/constraints.txt
 pip==24.0
 setuptools==71.0.0

requirements-netlify.txt

@@ -3,13 +3,13 @@ linkify-it-py
 plone-sphinx-theme
 sphinx-autobuild
 sphinx-copybutton
-sphinx-design
+sphinx-design  # Documentation only
 sphinx-examples
 sphinx-notfound-page  # Documentation only
 sphinx-reredirects
 sphinx-sitemap
-sphinxcontrib.httpdomain
-sphinxcontrib.httpexample
+sphinxcontrib.httpdomain  # plone.restapi
+sphinxcontrib.httpexample  # plone.restapi
 sphinxcontrib-video
 sphinxext-opengraph
 sphinxcontrib.mermaid