Merge pull request #539 from plone/contributing-plone-6

Overhaul contributing documentation for Plone 6

.github/workflows/docs.yml

@@ -6,7 +6,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [3.9]
+        python-version: [3.11]
 
     steps:
       # git checkout

.meta.toml

@@ -79,17 +79,15 @@ allowlist_externals =
 [testenv:plone6docs]
 # New docs with sphinx-book-theme
 # See [testenv:docs] for classic documentation
-basepython = python3.9
+basepython = python3.11
 skip_install = False
-usedevelop = True
+package = editable
 allowlist_externals =
     mkdir
 extras =
     tests
-
 deps =
     -r requirements-docs.txt
-
 commands =
     python -VV
     mkdir -p {toxinidir}/_build/plone6docs
@@ -116,9 +114,9 @@ whitelist_externals =
     mkdir
 
 [testenv:linkcheck]
-basepython = python
+basepython = python3.11
 skip_install = False
-usedevelop = True
+package = editable
 allowlist_externals =
     mkdir
 extras =

CONTRIBUTING.rst

@@ -1 +1 @@
-Please see https://5.docs.plone.org/develop/coredev/docs/guidelines.html
+Please see [Contributing to Plone](https://6.docs.plone.org/contributing/index.html) and [Contributing to `plone.api`](https://6.docs.plone.org/plone.api/contribute/index.html).

README.md

@@ -29,8 +29,7 @@ Recipes try to assume the user does not have extensive knowledge about Plone int
 
 
 Contributors
-    Please read the document [Process for Plone core's development](https://5.docs.plone.org/develop/coredev/docs/index.html).
-    Also consult the section about contribution in the [plone.api contributors documentation](https://5.docs.plone.org/develop/plone.api/docs/contribute/index.html).
+    Please read [Contributing to Plone](https://6.docs.plone.org/contributing/index.html) and [Contributing to `plone.api`](https://6.docs.plone.org/plone.api/contribute/index.html).
 
 Source Code
     at the [Plone code repository hosted at GitHub](https://github.com/plone/plone.api).

docs/conf.py

@@ -16,13 +16,14 @@
 }
 
 extensions = [
-    "sphinx.ext.doctest",
-    "sphinx.ext.coverage",
+    "myst_parser",
     "sphinx.ext.autodoc",
-    "sphinx.ext.viewcode",
     "sphinx.ext.autosummary",
-    "myst_parser",
+    "sphinx.ext.coverage",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
 ]
 master_doc = "index"
 
@@ -67,11 +68,12 @@ def __getattr__(cls, name):
     sys.modules[mod_name] = Mock()
 
 
-# -- Options for myST markdown conversion to html -----------------------------
+# -- Options for MyST markdown conversion to HTML -----------------------------
 
 myst_enable_extensions = [
     "colon_fence",
     "deflist",
+    "linkify",  # Identify "bare" web URLs and add hyperlinks.
 ]
 
 
@@ -81,3 +83,25 @@ def __getattr__(cls, name):
 # a list of builtin themes.
 #
 html_theme = "sphinx_book_theme"
+
+
+# -- Intersphinx configuration ----------------------------------
+
+# This extension can generate automatic links to the documentation of objects
+# in other projects. Usage is simple: whenever Sphinx encounters a
+# cross-reference that has no matching target in the current documentation set,
+# it looks for targets in the documentation sets configured in
+# intersphinx_mapping. A reference like :py:class:`zipfile.ZipFile` can then
+# linkto the Python documentation for the ZipFile class, without you having to
+# specify where it is located exactly.
+#
+# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
+#
+# Note that Plone Documentation imports documentation from several remote repositories.
+# These projects need to build their docs as part of their CI/CD and testing.
+# We use Intersphinx to resolve targets when either the individual project's or
+# the entire Plone Documentation is built.
+intersphinx_mapping = {
+    "plone": ("https://6.docs.plone.org/", None),  # for imported packages
+    "plone5": ("https://5.docs.plone.org/", None),
+}