Fix Sphinx toctree warnings from included CHANGELOG.md (plone#5135)

Co-authored-by: David Glick <[email protected]>
Co-authored-by: Victor Fernandez de Alba <[email protected]>

.gitignore

@@ -85,3 +85,4 @@ public/critical.css
 docs/_build/
 /.python-version
 /.tool-versions
+docs/source/news

CHANGELOG.md

@@ -1,3 +1,12 @@
+---
+myst:
+  html_meta:
+    "description": "Volto Release Notes for the Plone content management system"
+    "property=og:description": "Volto Release Notes for the Plone content management system"
+    "property=og:title": "Volto Release Notes"
+    "keywords": "Volto, Plone, frontend, Release Notes, change log, changelog, change history"
+---
+
 # Volto Release Notes
 
 <!-- You should *NOT* be adding new change log entries to this file.

Makefile

@@ -104,7 +104,11 @@ test:
 bin/python:
 	python3 -m venv . || virtualenv --clear --python=python3 .
 	bin/python -m pip install --upgrade pip
+	@echo "Python environment created."
 	bin/pip install -r requirements-docs.txt
+	@echo "Requirements installed."
+	ln -s ../../news ./docs/source/news
+	@echo "Symlink created."
 
 .PHONY: clean
 clean:
@@ -140,10 +144,7 @@ docs-linkcheck: bin/python  ## Run linkcheck
 
 .PHONY: docs-linkcheckbroken
 docs-linkcheckbroken: bin/python  ## 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/ ."
+	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 $$? -eq 0; then exit 1; fi || test $$? -ne 0
 
 .PHONY: docs-vale
 docs-vale:  ## Run Vale style, grammar, and spell checks
@@ -174,6 +175,11 @@ patches:
 corepackagebump:
 	node $(SCRIPTSPACKAGE)/corepackagebump.js packages/volto-slate $(VERSION)
 
+.PHONY: copyreleasenotestodocs
+copyreleasenotestodocs:
+	cp CHANGELOG.md docs/source/release-notes/index.md
+	git add docs/source/release-notes/index.md
+
 ##### Docker containers
 
 .PHONY: start-backend-docker

docs/source/conf.py

@@ -96,6 +96,7 @@
     r"https://github.com/plone/volto/issues/new/choose",
     r"https://github.com/plone/volto/blob/6fd62cb2860bc7cf3cb7c36ea86bfd8bd03247d9/src/components/manage/Form/Field.jsx#L112",
     r"https://github.com/tc39/proposals/blob/HEAD/finished-proposals.md#finished-proposals",
+    r"https://www.youtube.com/playlist",  # TODO uncomment after installing sphinxcontrib.youtube
 ]
 linkcheck_anchors = True
 linkcheck_timeout = 10
@@ -108,6 +109,11 @@
 # The suffix of source filenames.
 source_suffix = {
     ".md": "markdown",
+    ".bugfix": "markdown",
+    ".breaking": "markdown",
+    ".documentation": "markdown",
+    ".feature": "markdown",
+    ".internal": "markdown",
 }
 
 # The master toctree document.
@@ -118,11 +124,14 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = [
     "spelling_wordlist.txt",
-    "**/CHANGES.rst",
-    "**/LICENSE.rst",
     "contributing/branch-policy.md",
 ]
 
+suppress_warnings = [
+    # "toc.excluded",  # Suppress `WARNING: document isn't included in any toctree`
+    "toc.not_readable",  # Suppress `WARNING: toctree contains reference to nonexisting document 'news*'`
+]
+
 html_extra_path = [
     "robots.txt",
 ]

docs/source/index.md

@@ -38,3 +38,12 @@ user-manual/index
 contributing/index
 release-notes/index
 ```
+
+% Only check change log entries in Volto documentation—not when it is included in the main Plone documentation—to ensure links work and do not redirect.
+% It is OK to ignore warnings, such as the following:
+% docs/source/news/5280.bugfix: WARNING: document isn't included in any toctree
+````{ifconfig} context in ("volto",)
+```{toctree}
+news*
+```
+````

news/5135.documentation

@@ -0,0 +1 @@
+Fix Sphinx toctree warnings from included `CHANGELOG.md`. @stevepiercy

package.json

@@ -187,7 +187,7 @@
         "yarn i18n",
         "git add locales"
       ],
-      "after:bump": "pipx run towncrier build --draft --yes --version ${version} > .changelog.draft && pipx run towncrier build --yes --version ${version} && make corepackagebump VERSION=${version}",
+      "after:bump": "pipx run towncrier build --draft --yes --version ${version} > .changelog.draft && pipx run towncrier build --yes --version ${version} && make corepackagebump VERSION=${version} && make copyreleasenotestodocs",
       "after:release": "rm .changelog.draft"
     },
     "git": {