Clean up contributing docs and use RTD for pull request previews (#1798)

* Purge obsolete theme items and Netlify; Bump version

* Add pre-requisites and references to contributing to Plone in general

* Remove obsolete `make docs` and `bin/sphinxbuilder`

* Simplify Contributing

* news

* Purge Netlify

* Add RTD pull request preview workflow

* Use RTD to build docs and pull request previews

* Fix project slug

* Attempt to trigger RTD PR preview

* Override docutils pin from Zope

* Attempt to get all tests to pass with a special config for Plone 6 on Python 3.8

* Compare against `origin/main`

* Remove Python 3.7 section

.github/workflows/rtd-pr-preview.yml

@@ -0,0 +1,22 @@
+# .github/workflows/rtd-pr-preview.yml
+name: readthedocs/actions
+on:
+  pull_request_target:
+    types:
+      - opened
+    # Execute this action only on PRs that touch
+    # documentation files.
+    # paths:
+    #   - "docs/**"
+
+permissions:
+  pull-requests: write
+
+jobs:
+  documentation-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: readthedocs/actions/preview@v1
+        with:
+          project-slug: "plonerestapi"
+          single-version: "true"

.github/workflows/tests.yml

@@ -54,7 +54,7 @@ jobs:
 
       # buildout
       - name: buildout
-        run: buildout -t 10 -c plone-${{ matrix.plone-version }}.x.cfg
+        run: if [ "${{ matrix.plone-version }}" == "6.0" ] && [ ${{ matrix.python-version }} == '3.8' ]; then buildout -t 10 -c plone-6.0.x-python3.8.cfg; else buildout -t 10 -c plone-${{ matrix.plone-version }}.x.cfg; fi;
         env:
           CI: true
 

.readthedocs.yaml

@@ -5,25 +5,21 @@
 # Required
 version: 2
 
-# Set the version of Python and other tools you might need
+# Set the OS, Python version and other tools you might need
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
-    python: "3.9"
-    # You can also specify other tool versions:
-    # nodejs: "16"
-    # rust: "1.55"
-    # golang: "1.17"
-
-# Build documentation in the docs/ directory with Sphinx
-sphinx:
-  configuration: docs/source/conf.py
-
-# If using Sphinx, optionally build your docs in additional formats such as PDF
-# formats:
-#    - pdf
-
-# Optionally declare the Python requirements required to build your docs
-python:
-  install:
-    - requirements: requirements-docs.txt
+    python: "3.12"
+  commands:
+    # Cancel building pull requests when there aren't changes in the docs directory or YAML file.
+    # You can add any other files or directories that you'd like here as well,
+    # like your docs requirements file, or other files that will change your docs 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;
+      then
+        exit 183;
+      fi
+    - make rtd-pr-preview

Makefile

@@ -95,10 +95,6 @@ black:  ## Black
 zpretty:  ## zpretty
 	if [ -f "bin/zpretty" ]; then zpretty -i ./**/*.zcml; fi
 
-.PHONY: Build Docs
-docs:  ## Build Docs
-	bin/sphinxbuilder
-
 .PHONY: docs-clean
 docs-clean:  ## Clean current and legacy docs build directories, and Python virtual environment
 	cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/
@@ -138,10 +134,11 @@ docs-vale:  ## Run Vale style, grammar, and spell checks
 	@echo
 	@echo "Vale is finished; look for any errors in the above output."
 
-.PHONY: netlify
-netlify:
+.PHONY: rtd-pr-preview
+rtd-pr-preview:  ## Build pull request preview on Read the Docs
+	pip install -r requirements.txt
 	pip install -r requirements-docs.txt
-	cd $(DOCS_DIR) && sphinx-build -b html $(ALLSPHINXOPTS) ../$(BUILDDIR)/html
+	cd $(DOCS_DIR) && sphinx-build -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/
 
 .PHONY: Test Release
 test-release:  ## Run Pyroma and Check Manifest

docs/source/conf.py

@@ -34,7 +34,7 @@
 # built documents.
 # TODO: There must be a way to import this from `setup.py` so we don't have to
 # update it manually for each release.
-version = "8.24.2.dev0"
+version = "9.7.2.dev0"
 release = version
 
 # -- General configuration ----------------------------------------------------
@@ -176,15 +176,7 @@ def patch_pygments_to_highlight_jsonschema():
     "use_repository_button": True,
     "use_issues_button": True,
     "use_edit_page_button": True,
-    "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>""",
+    "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>""",
 }
 
 # Theme options are theme-specific and customize the look and feel of a theme

docs/source/contributing/index.md

@@ -1,13 +1,24 @@
 ---
 myst:
   html_meta:
-    "description": "Contributing to plone.restapi"
-    "property=og:description": "Contributing to plone.restapi"
-    "property=og:title": "Contributing to plone.restapi"
-    "keywords": "Plone, plone.restapi, REST, API, Contributing, documentation"
+    "description": "Contribute to plone.restapi"
+    "property=og:description": "Contribute to plone.restapi"
+    "property=og:title": "Contribute to plone.restapi"
+    "keywords": "Plone, plone.restapi, REST, API, contribute, documentation"
 ---
 
-# Contributing to `plone.restapi`
+# Contribute to `plone.restapi`
+
+This section describes how to contribute to the `plone.restapi` project.
+It extends {doc}`plone:contributing/index`.
+
+
+## Pre-requisites
+
+Prepare your system by installing {ref}`plone:plone-pre-requisites-label`.
+
+
+## Set up development environment
 
 We use GNU `make` when developing `plone.restapi`.
 To install this package, its dependencies, and its documentation, code formatting, and testing tools, run the following command in the root of the project.
@@ -16,21 +27,27 @@ To install this package, its dependencies, and its documentation, code formattin
 make
 ```
 
-## Generating documentation examples
+To see all the Makefile targets and help, use the following command.
+
+```shell
+make help
+```
+
+
+## Generate documentation examples
 
-This documentation includes examples of requests and responses (http, curl, httpie, and python-requests).
+This documentation includes examples of requests and responses, using each of http, curl, httpie, and python-requests.
 These examples are generated by the documentation tests in `test_documentation.py`.
-To generate a new example, add a new test case to `test_documentation.py`, for example `test_documentation_search_fullobjects`, and run the test
+To generate a new example, add a new test case to `test_documentation.py`, for example `test_documentation_search_fullobjects`, and run the test.
 
 ```shell
 ./bin/test -t test_documentation_search_fullobjects
 ```
 
-This generates the request and the response files in `tests/http-examples/`.
+The above command also generates the request and the response files in `tests/http-examples/`.
+Include them in the documentation using MyST syntax.
 
-Include them in the documentation using MyST syntax:
-
-````
+````markdown
 ```{eval-rst}
 ..  http:example:: curl httpie python-requests
     :request: ../../src/plone/restapi/tests/http-examples/search_fullobjects.req
@@ -40,31 +57,14 @@ Include them in the documentation using MyST syntax:
 ```
 ````
 
-Build the documentation locally to test the rendering by running `./bin/sphinxbuilder`.
-Alternatively, you can use Makefile targets:
-
-`docs-clean`
-: Clean current and legacy docs build directories, and Python virtual environment
-
-`docs-html`
-: Build HTML
-
-`docs-linkcheck`
-: Run linkcheck
-
-`docs-linkcheckbroken`
-: Run linkcheck and show only broken links
+Build the documentation locally to test the rendering.
 
-`docs-livehtml`
-: Rebuild Sphinx documentation on changes, with live-reload in the browser
-
-`docs-vale`
-: Run spell, grammar, and style checks
+```shell
+make docs-html
+```
 
-`docs`
-: Build Docs
+Add and commit the generated files in `src/plone/restapi/tests/http-examples/`.
 
-Make sure you add and commit the generated files in `http-examples`.
 
 ## Conventions
 
@@ -76,18 +76,18 @@ conventions
 
 ## Code formatting and testing
 
-To ensure consistent code formatting, we use [Black](https://black.readthedocs.io/en/stable/index.html).
-All pull requests must pass code formatting checks.
-We recommend that you run Black locally.
-You can use the following command to automatically format the code.
+All changes must pass code formatting and tests.
+Run these checks locally before creating a pull request.
+
+Use the following command to automatically format the code with [Black](https://black.readthedocs.io/en/stable/index.html).
 
 ```shell
 make black
 ```
 
-To run tests locally and ensure your changes don't introduce any issues, use the following command.
-This will execute the test suite and provide test feedback.
+Use the following command to run tests.
 
 ```shell
 make test
 ```
+

news/1798.documentation

@@ -0,0 +1 @@
+Update contributing docs for Plone 6, and switch from Netlify to Read the Docs for pull request previews. @stevepiercy

plone-6.0.x-python3.8.cfg

@@ -0,0 +1,17 @@
+[buildout]
+extends =
+    https://dist.plone.org/release/6.0.11.1/versions.cfg
+    base.cfg
+
+[instance]
+recipe = plone.recipe.zope2instance
+zodb-temporary-storage = off
+
+[versions]
+pygments = 2.14.0
+plone.app.linkintegrity = 4.0.3
+robotframework-browser = 17.5.2
+robotframework-assertion-engine = 2.0.0
+robotframework-debuglibrary = 2.3.0
+robotframework-pythonlibcore = 4.2.0
+grpcio-tools = 1.59.0

plone-6.0.x.cfg

@@ -13,6 +13,8 @@ recipe = plone.recipe.zope2instance
 zodb-temporary-storage = off
 
 [versions]
+# Override pin from Zope. https://github.com/zopefoundation/Zope/issues/1220
+docutils = 0.21.2
 pygments = 2.14.0
 plone.app.linkintegrity = 4.0.3
 robotframework-browser = 17.5.2

plone-6.1.x.cfg

@@ -12,4 +12,6 @@ parts =
 recipe = plone.recipe.zope2instance
 zodb-temporary-storage = off
 
-[versions]
+[versions]
+# Override pin from Zope. https://github.com/zopefoundation/Zope/issues/1220
+docutils = 0.21.2