Add documentation for how to administer Read the Docs for documentation

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

@@ -10,16 +10,16 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath("."))
+import os
+import sys
+sys.path.insert(0, os.path.abspath("../submodules/plone.api/src"))
 
 
 # -- Project information -----------------------------------------------------
 
 project = "Plone Documentation"
 copyright = "Plone Foundation"
-author = "the Plone community"
+author = "Plone Community"
 trademark_name = "Plone"
 now = datetime.now()
 year = str(now.year)
@@ -33,6 +33,7 @@
 # The full version, including alpha/beta/rc tags.
 release = "6.0"
 
+
 # -- General configuration ----------------------------------------------------
 
 # Add any paths that contain templates here, relative to this directory.
@@ -43,10 +44,14 @@
 # or your custom ones.
 extensions = [
     "myst_parser",
+    "notfound.extension",
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",  # plone.api
+    "sphinx.ext.graphviz",
     "sphinx.ext.ifconfig",
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
+    "sphinx.ext.viewcode",  # plone.api
     "sphinx_copybutton",
     "sphinx_design",
     "sphinx_examples",
@@ -56,10 +61,6 @@
     "sphinxcontrib.httpexample",  # plone.restapi
     "sphinxcontrib.video",
     "sphinxext.opengraph",
-    "sphinx.ext.viewcode",  # plone.api
-    "sphinx.ext.autosummary",  # plone.api
-    "sphinx.ext.graphviz",
-    "notfound.extension",
 ]
 
 # If true, the Docutils Smart Quotes transform, originally based on SmartyPants
@@ -144,18 +145,108 @@
     "toc.not_readable",  # Suppress `WARNING: toctree contains reference to nonexisting document 'news*'`
 ]
 
-html_js_files = ["patch_scrollToActive.js", "search_shortcut.js"]
 
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = "plone_sphinx_theme"
+html_logo = "_static/logo.svg"
+html_favicon = "_static/favicon.ico"
+html_theme_options = {
+    "article_header_start": ["toggle-primary-sidebar"],
+    "extra_footer": """<p>The text and illustrations in this website are licensed by the Plone Foundation under a Creative Commons Attribution 4.0 International license. Plone and the Plone® logo are registered trademarks of the Plone Foundation, registered in the United States and other countries. For guidelines on the permitted uses of the Plone trademarks, see <a href="https://plone.org/foundation/logo">https://plone.org/foundation/logo</a>. All other trademarks are owned by their respective owners.</p>
+<p>Pull request previews by <a href="https://readthedocs.org/" target="_blank">Read the Docs</a>.</p>""",
+    "footer_end": ["version.html"],
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/plone/documentation",
+            "icon": "fa-brands fa-square-github",
+            "type": "fontawesome",
+            "attributes": {
+                "target": "_blank",
+                "rel": "noopener me",
+                "class": "nav-link custom-fancy-css"
+            }
+        },
+        {
+            "name": "Twitter",
+            "url": "https://twitter.com/plone",
+            "icon": "fa-brands fa-square-twitter",
+            "type": "fontawesome",
+            "attributes": {
+                "target": "_blank",
+                "rel": "noopener me",
+                "class": "nav-link custom-fancy-css"
+            }
+        },
+        {
+            "name": "Mastodon",
+            "url": "https://plone.social/@plone",
+            "icon": "fa-brands fa-mastodon",
+            "type": "fontawesome",
+            "attributes": {
+                "target": "_blank",
+                "rel": "noopener me",
+                "class": "nav-link custom-fancy-css"
+            }
+        },
+    ],
+    "logo": {
+        "text": "Plone Documentation",
+    },
+    "navigation_with_keys": True,
+    "path_to_docs": "docs",
+    "repository_branch": "6.0",
+    "repository_url": "https://github.com/plone/documentation",
+    "search_bar_text": "Search",  # TODO: Confirm usage of search_bar_text in plone-sphinx-theme
+    "switcher": {
+        "json_url": "/_static/switcher.json",
+        "version_match": version,
+    },
+    "use_edit_page_button": True,
+    "use_issues_button": True,
+    "use_repository_button": True,
+}
+
+# suggest edit link
+# remark: {{ file_name }} is mandatory in "edit_page_url_template"
+html_context = {  # TODO: verify html_context usage in plone-sphinx-theme
+    "edit_page_url_template": "https://6.docs.plone.org/contributing/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
+html_use_opensearch = "https://6.docs.plone.org"  # TODO: Confirm usage of opensearch in theme
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+html_title = "%(project)s v%(release)s" % {"project": project, "release": release}
+
+# If false, no index is generated.
+html_use_index = True
+
+html_css_files = ["custom.css", ("print.css", {"media": "print"})]
+# html_js_files = ["patch_scrollToActive.js", "search_shortcut.js"]  ## TODO: Remove patches
 html_extra_path = [
     "robots.txt",
 ]
-
 html_static_path = [
     "volto/_static",
     "_static",  # Last path wins. See https://github.com/plone/documentation/pull/1442
 ]
 
-# -- Options for myST markdown conversion to html -----------------------------
+
+# -- 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}"
+
+
+# -- Options for MyST markdown conversion to HTML -----------------------------
 
 # For more information see:
 # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
@@ -179,6 +270,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
@@ -220,7 +312,12 @@
 ]
 
 
-# -- sphinx-notfound-page configuration ----------------------------------
+# -- Options for sphinx.ext.todo -----------------------
+# See http://sphinx-doc.org/ext/todo.html#confval-todo_include_todos
+todo_include_todos = True
+
+
+# -- Options for sphinx-notfound-page ----------------------------------
 
 notfound_urls_prefix = ""
 notfound_template = "404.html"
@@ -236,68 +333,6 @@
 }
 
 
-# -- Options for HTML output -------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-html_theme = "sphinx_book_theme"
-
-html_logo = "_static/logo.svg"
-html_favicon = "_static/favicon.ico"
-
-html_css_files = ["custom.css", ("print.css", {"media": "print"})]
-
-# See http://sphinx-doc.org/ext/todo.html#confval-todo_include_todos
-todo_include_todos = True
-
-# Announce that we have an opensearch plugin
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_use_opensearch
-html_use_opensearch = "https://6.docs.plone.org"
-
-html_sidebars = {
-    "**": [
-        "sidebar-logo.html",
-        "search-field.html",
-        "sbt-sidebar-nav.html",
-    ]
-}
-
-html_theme_options = {
-    "path_to_docs": "docs",
-    "repository_url": "https://github.com/plone/documentation",
-    "repository_branch": "main",
-    "use_repository_button": True,
-    "use_issues_button": True,
-    "use_edit_page_button": True,
-    "search_bar_text": "Search",
-    "switcher": {
-        "json_url": "/_static/switcher.json",
-        "version_match": version,
-    },
-    "extra_navbar": """
-    <p class="ploneorglink">
-        <a href="https://plone.org">
-            <img src="/_static/logo.svg" alt="plone.org" /> plone.org</a>
-    </p>""",
-    "extra_footer": """<p>The text and illustrations in this website are licensed by the Plone Foundation under a Creative Commons Attribution 4.0 International license. Plone and the Plone® logo are registered trademarks of the Plone Foundation, registered in the United States and other countries. For guidelines on the permitted uses of the Plone trademarks, see <a href="https://plone.org/foundation/logo">https://plone.org/foundation/logo</a>. All other trademarks are owned by their respective owners.</p>
-    <p><a href="https://www.netlify.com">
-  <img src="https://www.netlify.com/img/global/badges/netlify-color-bg.svg" alt="Deploys by Netlify" />
-</a></p>""",
-}
-
-# The name for this set of Sphinx documents.  If None, it defaults to
-# "<project> v<release> documentation".
-html_title = "%(project)s v%(release)s" % {"project": project, "release": release}
-
-# If false, no index is generated.
-html_use_index = True
-
-# 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}"
-
 # -- Options for HTML help output -------------------------------------------------
 
 # Output file base name for HTML help builder.
@@ -313,7 +348,7 @@
         "index",
         "PloneDocumentation.tex",
         "Plone Documentation",
-        "The Plone community",
+        "Plone Community",
         "manual",
     ),
 ]
@@ -323,12 +358,6 @@
 latex_logo = "_static/logo_2x.png"
 
 
-# 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",
-}
-
 # 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/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

@@ -165,7 +165,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.

docs/install/manage-add-ons-packages.md

@@ -50,7 +50,7 @@ For a complete list of features, usage, and options, read [`cookiecutter-zope-in
 
 This section describes how to manage packages for the Plone backend with `mxdev`.
 
-For developing add-ons for the Plone frontend, Volto, see {doc}`volto/addons/index`.
+For developing add-ons for the Plone frontend, Volto, see {doc}`/volto/addons/index`.
 
 
 (manage-the-problem-with-pip-label)=

requirements-initial.txt

@@ -1,4 +1,5 @@
+# requirements-initial.txt
 # From https://dist.plone.org/release/6-latest/constraints.txt
-pip==23.2
-setuptools==68.0.0
-wheel==0.40.0
+pip==24.0
+setuptools==69.5.1
+wheel==0.43.0