- Purged unused and broken build targets.

- Categorized targets with comments.
- Add test requirement `sphinx.ext.doctest` so that `make doctest` will work in some Plone projects.
- Add targets to correctly install, clean, and initialize the project.
- Switch to `uv` from `pip`.
- Fixed which changed files will build docs on RTD.
- Use a replacement for supported Python versions.
- Updated documentation with correct make commands.
- Move release command from `README.md` to `contribute.md`.

.github/workflows/test.yml

@@ -14,6 +14,7 @@ on:
       - '.github/workflows/test.yml'
       - '.readthedocs.yaml'
       - '.vale.ini'
+      - 'requirements.txt'
       - 'requirements-docs.txt'
 
 jobs:

.gitignore

@@ -1,4 +1,5 @@
 __pycache__
+/.lock
 /.nodeenv
 /_build
 /bin

.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/main -- docs/ .readthedocs.yaml requirements-initial.txt requirements-docs.txt;
+      if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .readthedocs.yaml requirements.txt requirements-docs.txt;
       then
         exit 183;
       fi

Makefile

@@ -25,197 +25,147 @@ VALEOPTS        ?=
 help:  # This help message
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
 
+# environment management
+.PHONY: bin/python
+bin/python:  ## Create Python virtual environment and install package requirements
+	python3 -m venv .
+	bin/pip install --upgrade pip setuptools uv wheel
+	bin/uv pip install -r requirements.txt
+
+.PHONY: docs
+docs: bin/python  ## Install documentation requirements into Python virtual environment
+	bin/uv pip install -r requirements-docs.txt -e .
+
+.PHONY: dev
+dev: docs  ## Install development requirements into Python virtual environment
+	bin/uv pip install -r requirements-dev.txt -e .
+
+.PHONY: update-deps
+update-deps:  ## Update
+	bin/uv pip install --upgrade pip setuptools uv wheel
+	bin/uv pip compile --upgrade pyproject.toml -o requirements.txt
+	bin/uv pip compile --upgrade pyproject.toml \
+		--extra docs -o requirements-docs.txt
+	bin/uv pip compile --upgrade pyproject.toml \
+		--extra docs --extra dev -o requirements-dev.txt
+
+.PHONY: init
+init: clean clean-python docs  ## Clean docs build directory and initialize Python virtual environment
+	bin/uv pip install -r requirements.txt -r requirements-docs.txt -r requirements-dev.txt -e .
+	bin/uv pip check
+
 .PHONY: clean
 clean:  ## Clean docs build directory
 	cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/
 
-.PHONY: distclean
-distclean:  ## Clean docs build directory and Python virtual environment
-	cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/
+.PHONY: clean-python
+clean-python: clean
 	rm -rf ./bin/ ./lib/ ./lib64 ./include ./pyvenv.cfg
+# /environment management
 
-bin/python:  ## Create Python virtual environment and install requirements
-	python3 -m venv .
-	bin/pip install ".[initial]"
-	bin/pip install ".[doc]"
-
-dev: bin/python  ##
-	bin/pip install ".[dev]"
-	bin/pip install -e .
-
+# documentation builders
 .PHONY: html
 html: bin/python  ## Build html
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
-.PHONY: manual
-manual: bin/python
-	cd $(DOCS_DIR) && $(SPHINXBUILD) -b html -t manual . $(BUILDDIR)/manual
+.PHONY: livehtml
+livehtml: docs  ## Rebuild Sphinx documentation on changes, with live-reload in the browser
+	cd "$(DOCS_DIR)" && ${SPHINXAUTOBUILD} \
+		--ignore "*.swp" \
+		--port 8050 \
+		-b html . "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
 
 .PHONY: dirhtml
-dirhtml: bin/python
+dirhtml: docs
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
 .PHONY: singlehtml
-singlehtml: bin/python
+singlehtml: docs
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
-.PHONY: pickle
-pickle: bin/python
-	cd $(DOCS_DIR) && $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-.PHONY: json
-json: bin/python
-	cd $(DOCS_DIR) && $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-.PHONY: htmlhelp
-htmlhelp: bin/python
-	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."
-
-.PHONY: qthelp
-qthelp: bin/python
-	cd $(DOCS_DIR) && $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
-	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/MasteringPlone.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/MasteringPlone.qhc"
-
-.PHONY: devhelp
-devhelp: bin/python
-	cd $(DOCS_DIR) && $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
-	@echo
-	@echo "Build finished."
-	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/MasteringPlone"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/MasteringPlone"
-	@echo "# devhelp"
-
-.PHONY: epub
-epub: bin/python
-	cd $(DOCS_DIR) && $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
-	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-
-.PHONY: latex
-latex: bin/python
-	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)."
-
-.PHONY: latexpdf
-latexpdf: bin/python
-	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."
-
 .PHONY: text
-text: bin/python
+text: docs
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
 	@echo
 	@echo "Build finished. The text files are in $(BUILDDIR)/text."
 
-.PHONY: man
-man: bin/python
-	cd $(DOCS_DIR) && $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
-	@echo
-	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
-
-.PHONY: texinfo
-texinfo: bin/python
-	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)."
-
-.PHONY: info
-info: bin/python
-	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."
-
 .PHONY: changes
-changes: bin/python
+changes: docs
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
 	@echo "The overview file is in $(BUILDDIR)/changes."
+# /documentation builders
 
+# test
 .PHONY: linkcheck
-linkcheck: bin/python  ## Run linkcheck
+linkcheck: docs  ## 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/ ."
 
 .PHONY: linkcheckbroken
-linkcheckbroken: bin/python  ## Run linkcheck and show only broken links
+linkcheckbroken: docs  ## 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/ ."
 
 .PHONY: vale
-vale: bin/python  ## Run Vale style, grammar, and spell checks
+vale: docs dev  ## Run Vale style, grammar, and spell checks
 	bin/vale sync
 	bin/vale --no-wrap $(VALEOPTS) $(VALEFILES)
 	@echo
 	@echo "Vale is finished; look for any errors in the above output."
 
-.PHONY: html_meta
-html_meta: bin/python  ## Add meta data headers to all Markdown pages
-	python ./docs/addMetaData.py
-
 .PHONY: doctest
-doctest: bin/python
+doctest: docs  ## Test snippets in the documentation
 	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."
 
 .PHONY: test
-test: clean linkcheckbroken  ## Clean docs build, then run linkcheckbroken
+test: clean vale linkcheckbroken doctest  ## Clean docs build, then run vale and linkcheckbroken
+# /test
 
-.PHONY: deploy
-deploy: clean html
-
-.PHONY: livehtml
-livehtml: bin/python  ## Rebuild Sphinx documentation on changes, with live-reload in the browser
-	cd "$(DOCS_DIR)" && ${SPHINXAUTOBUILD} \
-		--ignore "*.swp" \
-		--port 8050 \
-		-b html . "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
+# development
+.PHONY: html_meta
+html_meta: docs  ## Add meta data headers to all Markdown pages
+	python ./docs/addMetaData.py
 
-serve:  ## Compile static assets, build and serve the docs, and reload the browser on changes
-	bin/stb serve docs/
+.PHONY: kitchen-sink-update
+kitchen-sink-update:  ## Copy Kitchen Sink documentation files to Plone Sphinx Theme
+	bin/python scripts/kitchen_sink_update.py
 
 .PHONY: sbt-styles-update
 sbt-styles-update:  ## Copy Sphinx Book Theme styles to Plone Sphinx Theme
 	bin/python scripts/sbt_styles_update.py
 
-.PHONY: kitchen-sink-update
-kitchen-sink-update:  ## Copy Kitchen Sink documentation files to Plone Sphinx Theme
-	bin/python scripts/kitchen_sink_update.py
+.PHONY: serve
+serve:  ## Compile static assets, build and serve the docs, and reload the browser on changes
+	bin/stb serve docs/
+
+.PHONY: compile
+compile:  ## Compile static assets
+	bin/stb compile
 
 .PHONY: rtd-pr-preview
-rtd-pr-preview: bin/python  ## Build pull request preview on Read the Docs
+rtd-pr-preview: docs  ## Build pull request preview on Read the Docs
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/
 
+.PHONY: release
+release: dev compile  ## Release with zest.releaser
+	bin/fullrelease
+
 .PHONY: all
 all: clean vale linkcheck html  ## Clean docs build, then run vale and linkcheck, and build html
+# /development
+
+.PHONY: deploy
+deploy: clean html

README.md

@@ -8,27 +8,11 @@ It is based on [`sphinx-book-theme`](https://sphinx-book-theme.readthedocs.io/en
 ## Requirements
 
 -   Python 3.9, 3.10, 3.11, or 3.12
--   GNU Make is required only for contributing to or development of this theme.
+-   GNU Make is required only for building the documentation, contributing to, or development of this theme.
 
 
 ## Documentation
 
 Documentation is hosted on Read the Docs.
 
 https://plone-sphinx-theme.readthedocs.io/
-
-
-## Demonstration
-
-TODO: Add reference to documentation permanent URL.
-
-To build documentation and a demonstration of this project, you can use `make` commands.
-
-
-## Releasing
-
-Run the following command.
-
-```shell
-fullrelease
-```

docs/conf.py

@@ -59,6 +59,7 @@
     "notfound.extension",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",  # plone.api
+    "sphinx.ext.doctest",  # plone.api
     "sphinx.ext.graphviz",
     "sphinx.ext.ifconfig",
     "sphinx.ext.intersphinx",
@@ -96,6 +97,7 @@
     r"https://github.com/orgs/plone/teams/",  # requires auth
     r"https://github.com/plone/documentation/issues/new/choose",  # requires auth
     r"https://github.com/plone/volto/issues/new/choose",  # requires auth
+    r"https://github.com/plone/plone-sphinx-theme/issues/new",  # requires auth
     # Ignore github.com pages with anchors
     r"https://github.com/.*#.*",
     # Ignore other specific anchors
@@ -406,9 +408,9 @@ def source_replace(app, docname, source):
 # Dict of replacements.
 source_replacements = {
     "{PLONE_BACKEND_MINOR_VERSION}": "6.0",
-    "{PLONE_BACKEND_PATCH_VERSION}": "6.0.11",
+    "{PLONE_BACKEND_PATCH_VERSION}": "6.0.13",
     "{NVM_VERSION}": "0.39.5",
-    "{SUPPORTED_PYTHON_VERSIONS}": "3.8, 3.9, 3.10, 3.11, or 3.12",
+    "{SUPPORTED_PYTHON_VERSIONS}": "3.9, 3.10, 3.11, or 3.12",
 }
 
 

docs/guides/contribute.md

@@ -12,9 +12,10 @@ myst:
 This document describes how to install Plone Sphinx Theme for contributing code to this project, and what you can modify.
 It also covers the essential commands for building and previewing
 
+
 ## Prerequisites
 
--   A supported version of Python, as specified on this documentation's {doc}`home page <../index>`
+-   Python {SUPPORTED_PYTHON_VERSIONS}
 -   {term}`GNU Make`
 
 
@@ -103,7 +104,7 @@ See {ref}`update-parent-theme-styles` for details.
 After editing any of the static assets, you need to compile them.
 
 ```shell
-stb compile
+make compile
 ```
 
 
@@ -124,3 +125,14 @@ make sbt-styles-update
 
 Plone Sphinx Theme uses webpack to compile a JavaScript file for its theme.
 You can edit these files located in the directory {file}`src/plone_sphinx_theme/assets/scripts`.
+
+
+## Release
+
+To release Plone Sphinx Theme, use the following command.
+
+```shell
+make release
+```
+
+This command runs [`zest.releaser`](https://pypi.org/project/zest.releaser/) to make a full release.

docs/guides/contributing-policies.md

@@ -32,7 +32,7 @@ A copy of the license is included in the root of this repository.
 
 A volunteer member of the Plone Foundation will review your signed agreement.
 
-If accepted, your GitHub account will be added to a team in the Plone GitHub organization with appropriate access, and you will simultaneously receive an email notification from GitHub.
+If accepted, your GitHub account will be added to a team in the Plone GitHub organization with appropriate access, and you will simultaneously receive an email from GitHub for you to accept the invitation to join the team.
 
 Allow up to one week for processing.
 Contact the Plone Foundation by its email address for further information, including the status of your request.