From f9aa852f50c994621572bb69e5e0b8e8c85777b0 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 22 Jul 2024 04:30:30 +0200 Subject: [PATCH 01/16] Purge obsolete theme items and Netlify; Bump version --- Makefile | 5 ----- docs/source/conf.py | 12 ++---------- 2 files changed, 2 insertions(+), 15 deletions(-) diff --git a/Makefile b/Makefile index eb379c7b74..2e3306611a 100644 --- a/Makefile +++ b/Makefile @@ -138,11 +138,6 @@ 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: - pip install -r requirements-docs.txt - cd $(DOCS_DIR) && sphinx-build -b html $(ALLSPHINXOPTS) ../$(BUILDDIR)/html - .PHONY: Test Release test-release: ## Run Pyroma and Check Manifest bin/pyroma -n 10 -d . diff --git a/docs/source/conf.py b/docs/source/conf.py index d8e125b8f4..c1cb7ad6f7 100644 --- a/docs/source/conf.py +++ b/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": """ -

- - plone.org plone.org -

""", - "extra_footer": """

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 https://plone.org/foundation/logo. All other trademarks are owned by their respective owners.

-

- Deploys by Netlify -

""", + "extra_footer": """

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 https://plone.org/foundation/logo. All other trademarks are owned by their respective owners.

""", } # Theme options are theme-specific and customize the look and feel of a theme From 6b5ca136e0ba9d48d6aa5c1217722c2d0f02613f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 22 Jul 2024 04:33:23 +0200 Subject: [PATCH 02/16] Add pre-requisites and references to contributing to Plone in general --- docs/source/contributing/index.md | 31 ++++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/docs/source/contributing/index.md b/docs/source/contributing/index.md index 5654a396d4..a77e26603b 100644 --- a/docs/source/contributing/index.md +++ b/docs/source/contributing/index.md @@ -1,13 +1,29 @@ --- 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 pre-requisites. + + +### System libraries + +See {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,7 +32,8 @@ To install this package, its dependencies, and its documentation, code formattin make ``` -## Generating documentation examples + +## Generate documentation examples This documentation includes examples of requests and responses (http, curl, httpie, and python-requests). These examples are generated by the documentation tests in `test_documentation.py`. @@ -30,7 +47,7 @@ This generates the request and the response files in `tests/http-examples/`. 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 From a6be63acc896dd9a53e2e5778e1f5dd79ac359bb Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 24 Jul 2024 02:38:20 +0200 Subject: [PATCH 03/16] Remove obsolete `make docs` and `bin/sphinxbuilder` --- Makefile | 4 ---- docs/source/contributing/index.md | 3 +-- 2 files changed, 1 insertion(+), 6 deletions(-) diff --git a/Makefile b/Makefile index 2e3306611a..d0d48c5e20 100644 --- a/Makefile +++ b/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)/ diff --git a/docs/source/contributing/index.md b/docs/source/contributing/index.md index a77e26603b..90d411dffb 100644 --- a/docs/source/contributing/index.md +++ b/docs/source/contributing/index.md @@ -57,8 +57,7 @@ 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: +Build the documentation locally to test the rendering using the appropriate Makefile target. `docs-clean` : Clean current and legacy docs build directories, and Python virtual environment From 948eae6cef893babf88e2fd64802eedb2a31a4d9 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 27 Jul 2024 10:21:15 -0700 Subject: [PATCH 04/16] Simplify Contributing --- docs/source/contributing/index.md | 61 +++++++++++-------------------- 1 file changed, 22 insertions(+), 39 deletions(-) diff --git a/docs/source/contributing/index.md b/docs/source/contributing/index.md index 90d411dffb..0303c19fe6 100644 --- a/docs/source/contributing/index.md +++ b/docs/source/contributing/index.md @@ -10,17 +10,12 @@ myst: # Contribute to `plone.restapi` This section describes how to contribute to the `plone.restapi` project. -It extends {doc}`plone:contributing/index`. +It extends {doc}`plone:contributing/index`. ## Pre-requisites -Prepare your system by installing pre-requisites. - - -### System libraries - -See {ref}`plone:plone-pre-requisites-label`. +Prepare your system by installing {ref}`plone:plone-pre-requisites-label`. ## Set up development environment @@ -32,20 +27,25 @@ To install this package, its dependencies, and its documentation, code formattin make ``` +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/`. - -Include them in the documentation using MyST syntax: +The above command also generates the request and the response files in `tests/http-examples/`. +Include them in the documentation using MyST syntax. ````markdown ```{eval-rst} @@ -57,30 +57,14 @@ Include them in the documentation using MyST syntax: ``` ```` -Build the documentation locally to test the rendering using the appropriate Makefile target. +Build the documentation locally to test the rendering. -`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 - -`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 @@ -92,17 +76,16 @@ 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 From 244edbfc00a1600305f93f3cbdf07b7d7b3f67ce Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 27 Jul 2024 15:16:41 -0700 Subject: [PATCH 05/16] news --- news/1798.documentation | 1 + 1 file changed, 1 insertion(+) create mode 100644 news/1798.documentation diff --git a/news/1798.documentation b/news/1798.documentation new file mode 100644 index 0000000000..295dee06ae --- /dev/null +++ b/news/1798.documentation @@ -0,0 +1 @@ +Update contributing docs for Plone 6. @stevepiercy From ef8ce8433ecf2ae1d8717b36bcd44e4c4ed056d1 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 27 Jul 2024 15:18:19 -0700 Subject: [PATCH 06/16] Purge Netlify --- netlify.toml | 5 ----- 1 file changed, 5 deletions(-) delete mode 100644 netlify.toml diff --git a/netlify.toml b/netlify.toml deleted file mode 100644 index 9d440d0eb9..0000000000 --- a/netlify.toml +++ /dev/null @@ -1,5 +0,0 @@ -[build.environment] - PYTHON_VERSION = "3.8" - -[build] - ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF ./docs/" From c2a4c555600140687f8d22159b45e0397e473208 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 27 Jul 2024 15:22:41 -0700 Subject: [PATCH 07/16] Add RTD pull request preview workflow --- .github/workflows/rtd-pr-preview.yml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 .github/workflows/rtd-pr-preview.yml diff --git a/.github/workflows/rtd-pr-preview.yml b/.github/workflows/rtd-pr-preview.yml new file mode 100644 index 0000000000..449de0d7a8 --- /dev/null +++ b/.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: "plone.restapi" + single-version: "true" From bbf9c2e03d9ec4cb774e966903402ae50e069659 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 27 Jul 2024 15:29:44 -0700 Subject: [PATCH 08/16] Use RTD to build docs and pull request previews --- .readthedocs.yaml | 36 ++++++++++++++++-------------------- Makefile | 6 ++++++ docs/requirements.txt | 2 -- 3 files changed, 22 insertions(+), 22 deletions(-) delete mode 100644 docs/requirements.txt diff --git a/.readthedocs.yaml b/.readthedocs.yaml index deeaa762f7..b89586a1ad 100644 --- a/.readthedocs.yaml +++ b/.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/6.0 -- docs/ .readthedocs.yaml requirements-docs.txt requirements.txt; + then + exit 183; + fi + - make rtd-pr-preview diff --git a/Makefile b/Makefile index d0d48c5e20..71c500930e 100644 --- a/Makefile +++ b/Makefile @@ -134,6 +134,12 @@ docs-vale: ## Run Vale style, grammar, and spell checks @echo @echo "Vale is finished; look for any errors in the above output." +.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) ${READTHEDOCS_OUTPUT}/html/ + .PHONY: Test Release test-release: ## Run Pyroma and Check Manifest bin/pyroma -n 10 -d . diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index 82f259eacf..0000000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,2 +0,0 @@ -sphinxcontrib.httpdomain -sphinxcontrib.httpexample \ No newline at end of file From c943812fba5007237ac24e81d7cc6bbd7642e71c Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 27 Jul 2024 15:31:48 -0700 Subject: [PATCH 09/16] Update news --- news/1798.documentation | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/news/1798.documentation b/news/1798.documentation index 295dee06ae..b56db95533 100644 --- a/news/1798.documentation +++ b/news/1798.documentation @@ -1 +1 @@ -Update contributing docs for Plone 6. @stevepiercy +Update contributing docs for Plone 6, and switch from Netlify to Read the Docs for pull request previews. @stevepiercy From b65e2fcd8d84eab7e6563f177d48392ee87dd90e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 27 Jul 2024 15:36:01 -0700 Subject: [PATCH 10/16] Fix project slug --- .github/workflows/rtd-pr-preview.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/rtd-pr-preview.yml b/.github/workflows/rtd-pr-preview.yml index 449de0d7a8..28e329ecf6 100644 --- a/.github/workflows/rtd-pr-preview.yml +++ b/.github/workflows/rtd-pr-preview.yml @@ -18,5 +18,5 @@ jobs: steps: - uses: readthedocs/actions/preview@v1 with: - project-slug: "plone.restapi" + project-slug: "plonerestapi" single-version: "true" From 4130551a16df756b5277e97457f4aa62b8283d91 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 27 Jul 2024 15:43:47 -0700 Subject: [PATCH 11/16] Attempt to trigger RTD PR preview --- docs/source/contributing/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/contributing/index.md b/docs/source/contributing/index.md index 0303c19fe6..1c0c9ac617 100644 --- a/docs/source/contributing/index.md +++ b/docs/source/contributing/index.md @@ -90,3 +90,4 @@ Use the following command to run tests. ```shell make test ``` + From 0057d06d6a5161c51b07bfbe171b147f82478186 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 27 Jul 2024 15:50:35 -0700 Subject: [PATCH 12/16] Override docutils pin from Zope --- plone-6.0.x.cfg | 2 ++ 1 file changed, 2 insertions(+) diff --git a/plone-6.0.x.cfg b/plone-6.0.x.cfg index 5c418ddfe0..5172c9ddaf 100644 --- a/plone-6.0.x.cfg +++ b/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 From 0371c1578491432c850f604ba9b384ea22e4b7c8 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 27 Jul 2024 15:58:38 -0700 Subject: [PATCH 13/16] Override docutils pin from Zope --- plone-6.1.x.cfg | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/plone-6.1.x.cfg b/plone-6.1.x.cfg index 2ac1f2b5af..54716fa951 100644 --- a/plone-6.1.x.cfg +++ b/plone-6.1.x.cfg @@ -12,4 +12,6 @@ parts = recipe = plone.recipe.zope2instance zodb-temporary-storage = off -[versions] \ No newline at end of file +[versions] +# Override pin from Zope. https://github.com/zopefoundation/Zope/issues/1220 +docutils = 0.21.2 From a24162d82096d1be68107f8b4c7c7db9b6320726 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 27 Jul 2024 16:26:30 -0700 Subject: [PATCH 14/16] Attempt to get all tests to pass with a special config for Plone 6 on Python 3.8 --- .github/workflows/tests.yml | 2 +- plone-6.0.x-python3.8.cfg | 22 ++++++++++++++++++++++ 2 files changed, 23 insertions(+), 1 deletion(-) create mode 100644 plone-6.0.x-python3.8.cfg diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index b93241b9dd..b354a9e4d5 100644 --- a/.github/workflows/tests.yml +++ b/.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 diff --git a/plone-6.0.x-python3.8.cfg b/plone-6.0.x-python3.8.cfg new file mode 100644 index 0000000000..5c418ddfe0 --- /dev/null +++ b/plone-6.0.x-python3.8.cfg @@ -0,0 +1,22 @@ +[buildout] +extends = + https://dist.plone.org/release/6.0.11.1/versions.cfg + base.cfg + +[buildout:python37] +parts = + test + code-analysis + +[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 From 5f2017aa4502cfc242b8f7e7ad96f52f7c2856cf Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 2 Aug 2024 22:11:34 -0700 Subject: [PATCH 15/16] Compare against `origin/main` --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index b89586a1ad..0bf1b9ba85 100644 --- a/.readthedocs.yaml +++ b/.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/6.0 -- docs/ .readthedocs.yaml requirements-docs.txt requirements.txt; + if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .readthedocs.yaml requirements-docs.txt requirements.txt; then exit 183; fi From d6bd7804ffacf07ce18647b84e9f07e9e7b0124b Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 2 Aug 2024 22:19:49 -0700 Subject: [PATCH 16/16] Remove Python 3.7 section --- plone-6.0.x-python3.8.cfg | 5 ----- 1 file changed, 5 deletions(-) diff --git a/plone-6.0.x-python3.8.cfg b/plone-6.0.x-python3.8.cfg index 5c418ddfe0..9fca1a2f0e 100644 --- a/plone-6.0.x-python3.8.cfg +++ b/plone-6.0.x-python3.8.cfg @@ -3,11 +3,6 @@ extends = https://dist.plone.org/release/6.0.11.1/versions.cfg base.cfg -[buildout:python37] -parts = - test - code-analysis - [instance] recipe = plone.recipe.zope2instance zodb-temporary-storage = off