Switch to Plone Sphinx Theme for documentation, include changes to ht…

…tp-examples to build docs preview (#1815)

* Include changes to http-examples to build docs preview

* Remove obsolete styles and template

* Update requirements-docs.txt and conf.py to align with minimal Plone Sphinx Theme

* Update requirements-docs.txt and conf.py to align with minimal Plone Sphinx Theme

* Only install docs requirements when building docs

* Add setuptools to requirements-docs.txt because sphinxcontrib.httpexample requires its pkg_resources

* improve comment for future developers

* news

* Remove commented code

* Move legacy commented setting descriptions above their settings

* Move python-clean into a separate make target, so docs-clean does not obliterate the virtual environment. Most of the time, I just want to purge the built docs, not the virtual environment.

.github/workflows/tests.yml

@@ -50,7 +50,7 @@ jobs:
       - run: pip install virtualenv
       - run: pip install wheel
       - name: pip install
-        run: pip install -r requirements-${{ matrix.plone-version }}.txt -r requirements-docs.txt
+        run: pip install -r requirements-${{ matrix.plone-version }}.txt
 
       # buildout
       - name: buildout
@@ -60,7 +60,7 @@ jobs:
 
       # build sphinx
       - name: sphinx
-        run: if [ "${{ matrix.plone-version }}" == "6.0" ] && [ ${{ matrix.python-version }} == '3.12' ]; then make docs-html; fi
+        run: if [ "${{ matrix.plone-version }}" == "6.0" ] && [ ${{ matrix.python-version }} == '3.12' ]; then pip install -r requirements-docs.txt && make docs-html; fi
 
       # test
       - name: test

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

Makefile

@@ -95,10 +95,13 @@ black:  ## Black
 zpretty:  ## zpretty
 	if [ -f "bin/zpretty" ]; then zpretty -i ./**/*.zcml; fi
 
+.PHONY: python-clean
+python-clean:  ## Clean Python virtual environment
+	rm -rf bin include lib
+
 .PHONY: docs-clean
-docs-clean:  ## Clean current and legacy docs build directories, and Python virtual environment
+docs-clean:  ## Clean current and legacy docs build directories
 	cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/
-	rm -rf bin include lib
 	rm -rf docs/build
 
 .PHONY: docs-html