Merge pull request #31 from plone/vale-enhance

Upgrade and pin Vale to v3

.github/workflows/test.yml

@@ -0,0 +1,49 @@
+name: Build documentation, check links, spelling, grammar, and style
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+  # Build pull requests
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'styles/**'
+      - '.github/workflows/rtd-pr-preview.yml'
+      - '.github/workflows/test.yml'
+      - '.readthedocs.yaml'
+      - '.vale.ini'
+      - 'requirements-docs.txt'
+
+jobs:
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.12']
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+          cache-dependency-path: 'requirements-docs.txt'
+
+      - name: Create Python virtual environment
+        run: pip install virtualenv
+
+      - name: pip install requirements
+        run: pip install -r requirements-docs.txt
+
+      - name: Check for broken links
+        run: make linkcheckbroken
+
+      - name: Build HTML documentation
+        run: make html
+
+      - name: Run vale
+        run: make vale VALEOPTS="--minAlertLevel='warning'"

Makefile

@@ -17,6 +17,7 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 VALEFILES       := $(shell find $(DOCS_DIR) -type f -name "*.md" -print)
+VALEOPTS        ?=
 
 # Add the following 'help' target to your Makefile
 # And add help text after each target name starting with '\#\#'
@@ -174,7 +175,7 @@ linkcheckbroken: bin/python  ## Run linkcheck and show only broken links
 .PHONY: vale
 vale: bin/python  ## Run Vale style, grammar, and spell checks
 	bin/vale sync
-	bin/vale --no-wrap $(VALEFILES)
+	bin/vale --no-wrap $(VALEOPTS) $(VALEFILES)
 	@echo
 	@echo "Vale is finished; look for any errors in the above output."
 

docs/conf.py

@@ -88,6 +88,7 @@
     r"http://0.0.0.0",
     r"http://127.0.0.1",
     r"http://localhost",
+    r"http://someurl",
     r"http://yoursite",
     # Ignore file downloads
     r"^/_static/",
@@ -105,6 +106,7 @@
     r"https://chromewebstore.google.com/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi",  # TODO retest with latest Sphinx when upgrading theme. chromewebstore recently changed its URL and has "too many redirects".
     r"https://chromewebstore.google.com/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd",  # TODO retest with latest Sphinx when upgrading theme. chromewebstore recently changed its URL and has "too many redirects".
     r"https://stackoverflow.com",  # volto and documentation  # TODO retest with latest Sphinx.
+    r"https://.*unsplash.com/",  # plone-sphinx-theme
     r"https://web.archive.org/",  # volto
     r"https://www.youtube.com/playlist",  # volto, TODO remove after installing sphinxcontrib.youtube
 ]

docs/glossary.md

@@ -58,4 +58,11 @@ Open Graph
     The [Open Graph protocol](https://ogp.me/) enables any web page to become a rich object in a social graph.
     For instance, this is used on Facebook to allow any web page to have the same functionality as any other object on Facebook.
 
+Make
+make
+GNU make
+    [GNU Make](https://www.gnu.org/software/make/) is a tool which controls the generation of executables and other non-source files of a program from the program's source files.
+
+    Make gets its knowledge of how to build your program from a file called the _makefile_, which lists each of the non-source files and how to compute it from other files.
+    When you write a program, you should write a makefile for it, so that it is possible to use Make to build and install the program.
 ```

docs/guides/contribute.md

@@ -15,7 +15,7 @@ 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>`
--   GNU Make
+-   {term}`GNU Make`
 
 
 ## Install Plone Sphinx Theme
@@ -54,7 +54,7 @@ See {ref}`update-kitchen-sink-demonstration` for details.
 
 ### Update Kitchen Sink demonstration
 
-From time to time, the demonstration files for [Sphinx Themes Gallery](https://sphinx-themes.org/) will be updated.
+From time to time, the demonstration files for [Sphinx Themes Gallery](https://sphinx-themes.org/) need to be updated.
 Plone Sphinx Theme uses these files as a demonstration for its styles.
 To copy these updated files to Plone Sphinx Theme, run the following command.
 
@@ -76,7 +76,7 @@ This section describes how you can change this theme.
 ### Add or edit a template
 
 Templates are pages of Jinja2 code into which components can be inserted.
-Plone Sphinx Theme uses a template, {file}`404.html` to display an HTTP "404 Not Found" response page to visitors when they request a page that does not exist.
+Plone Sphinx Theme uses a template, {file}`404.html` to display an HTTP "404 Not Found" response page to visitors when they request a page that doesn't exist.
 In Plone Sphinx Theme, templates are located in the directory {file}`src/plone_sphinx_theme/theme/plone-sphinx-theme`.
 
 

docs/guides/contributing-policies.md

@@ -23,11 +23,11 @@ To develop your own theme based on Plone Sphinx Theme, see {doc}`develop`.
 
 ## Grant permission to publish
 
-Before you contribute, you must give permission to publish your contribution according to the license we use.
+Before you contribute, you must give permission to publish your contribution according to the license that Plone uses.
 You may give that permission by signing the [Plone Contributor Agreement](https://plone.org/foundation/contributors-agreement).
-It is a one-time only process.
+It's a one-time only process.
 
-The Plone Sphinx Theme Documentation is licensed under the [GNU General Public License, version 2 (GPLv2)](https://github.com/plone/plone-sphinx-theme/blob/main/LICENSE.md).
+The Plone Sphinx Theme Documentation is licensed under the [GNU General Public License, version 2 (GPLv2)](https://github.com/plone/plone-sphinx-theme/blob/main/LICENSE).
 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.

docs/reference/extensions.md

@@ -33,25 +33,25 @@ These extensions are built in and can be activated by respective entries in the
 -   [`myst_parser`](https://myst-parser.readthedocs.io/en/latest/) parses MyST, a rich and extensible flavour of Markdown for authoring documentation.
 -   [`sphinx-design`](https://sphinx-design.readthedocs.io/en/latest/), with a configuration name of `sphinx_design`, adds grids, cards, icons, badges, buttons, tabs, and dropdowns.
 -   [`sphinx-examples`](https://ebp-sphinx-examples.readthedocs.io/en/latest/) adds "example snippets" that allow you to show off source Markdown and the result of rendering it in Sphinx.
--   [`sphinx-notfound-page`](https://sphinx-notfound-page.readthedocs.io/en/latest/index.html), with a configuration name of `notfound.extension`, creates a custom 404 page and helps generate proper static resource links to render the page properly.
+-   [`sphinx-notfound-page`](https://sphinx-notfound-page.readthedocs.io/en/latest/index.html), with a configuration name of `notfound.extension`, creates a custom 404 page and helps generate proper static resource links to render the page.
 -   [`sphinx.ext.autodoc`](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) pulls in documentation from Python docstrings to generate reStructuredText which in turn gets parsed by Sphinx and rendered to the output format.
-    It is used by {doc}`plone:plone.api/index`.
+    It's used by {doc}`plone:plone.api/index`.
 -   [`sphinx.ext.autosummary`](https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html) generates function/method/attribute summary lists.
-    It is used by {doc}`plone:plone.api/index`.
+    It's used by {doc}`plone:plone.api/index`.
 -   [`sphinx.ext.graphviz`](https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html) allows you to embed [Graphviz](https://graphviz.org/download/) graphs in your documents.
 -   [`sphinx.ext.ifconfig`](https://www.sphinx-doc.org/en/master/usage/extensions/ifconfig.html) includes content based on configuration.
 -   [`sphinx.ext.intersphinx`](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html) provides linking between separate projects that use Sphinx for documentation.
 -   [`sphinx.ext.todo`](https://www.sphinx-doc.org/en/master/usage/extensions/todo.html) adds support for todo items.
 -   [`sphinx.ext.viewcode`](https://www.sphinx-doc.org/en/master/usage/extensions/viewcode.html) generates pages of source code modules and links between the source and the description.
-    It is used by {doc}`plone:plone.api/index`.
+    It's used by {doc}`plone:plone.api/index`.
 -   [`sphinx_copybutton`](https://sphinx-copybutton.readthedocs.io/en/latest/index.html)  adds a little "copy" button to the right of code blocks.
 -   [`sphinx_reredirects`](https://documatt.com/sphinx-reredirects/) handles redirects for moved pages.
 -   [`sphinx_sitemap`](https://pypi.org/project/sphinx-sitemap/) generates multiversion and multilanguage [sitemaps.org](https://www.sitemaps.org/protocol.html) compliant sitemaps.
 -   [`sphinxcontrib.httpdomain`](https://sphinxcontrib-httpdomain.readthedocs.io/en/stable/) provides a Sphinx domain for describing HTTP APIs.
-    It is used by Plone's {doc}`plone:plone.restapi/docs/source/index`.
+    It's used by Plone's {doc}`plone:plone.restapi/docs/source/index`.
 -   [`sphinxcontrib.httpexample`](https://sphinxcontrib-httpexample.readthedocs.io/en/latest/) enhances `sphinxcontrib-httpdomain` by generating RESTful HTTP API call examples for different tools from a single HTTP request example.
     Supported tools include [`curl`](https://curl.se/), [`wget`](https://www.gnu.org/software/wget/), [`httpie`](https://httpie.io/), and [`python-requests`](https://requests.readthedocs.io/en/latest/).
-    It is used by Plone's {doc}`plone:plone.restapi/docs/source/index`.
+    It's used by Plone's {doc}`plone:plone.restapi/docs/source/index`.
 % -   [`sphinxcontrib.mermaid`](https://pypi.org/project/sphinxcontrib-mermaid/) allows you to embed [Mermaid](https://mermaid.js.org/) graphs in your documents, including general flowcharts, sequence diagrams, and Gantt charts.
 -   [`sphinxcontrib.video`](https://pypi.org/project/sphinxcontrib-video/) allows you to embed local videos as defined by the HTML5 standard.
 -   [`sphinxext.opengraph`](https://pypi.org/project/sphinxext-opengraph/) generates [OpenGraph metadata](https://ogp.me/).

docs/reference/file-system-structure.md

@@ -56,10 +56,10 @@ Plone Sphinx Theme's file structure follows [that of Sphinx Theme Builder](https
 ## Autogenerated directories
 
 The following directories will be autogenerated when the theme's assets are compiled.
-They are included in the project's {file}`.gitignore` file.
+They're included in the project's {file}`.gitignore` file.
 
 `.nodeenv`
-:   The Node.js installation that is used to compile the theme's assets.
+:   The Node.js installation that's used to compile the theme's assets.
 
 `node_modules`
 :   The Node.js packages that are installed to compile the theme's assets.

news/31.feature

@@ -0,0 +1,3 @@
+Upgrade and pin Vale to v3. @stevepiercy
+- Follow some of Vale's suggestions and fix errors and warnings. @stevepiercy
+- Add GitHub Workflow to build docs and run checks on links, spelling, grammar, and style. @stevepiercy

pyproject.toml

@@ -64,7 +64,7 @@ doc = [
   "sphinxcontrib.httpexample",
   "sphinxcontrib-video",
   "sphinxext-opengraph",
-  "vale==2.30.0",
+  "vale",
 #  Commented from Sphinx Book Theme.
 #  Uncomment to install, then configure in conf.py.
 #    "ablog",
@@ -97,7 +97,7 @@ Repository = "https://github.com/plone/plone-sphinx-theme"
 Documentation = "https://github.com/plone/plone-sphinx-theme"
 
 [build-system]
-requires = ["setuptools >= 69.5"]
+requires = ["setuptools >= 74.0.0"]
 build-backend = "setuptools.build_meta"
 
 [tool.sphinx-theme-builder]

requirements-docs.txt

@@ -1,18 +1,18 @@
 # requirements-docs.txt
-graphviz
-linkify-it-py
-myst-parser
-plone-sphinx-theme
-sphinx-autobuild
-sphinx-copybutton
-sphinx-design
-sphinx-examples
-sphinx-notfound-page
-sphinx-reredirects
-sphinx-sitemap
-sphinxcontrib.httpdomain
-sphinxcontrib.httpexample
-# sphinxcontrib-mermaid  # See https://github.com/mgaitan/sphinxcontrib-mermaid/issues/137
-sphinxcontrib-video
-sphinxext-opengraph
-vale==2.30.0
+graphviz==0.20.3
+linkify-it-py==2.0.3
+myst-parser==3.0.1
+Sphinx==7.4.7
+sphinx-autobuild==2024.4.16
+sphinx-copybutton==0.5.2
+sphinx-examples==0.0.5
+sphinx-notfound-page==1.0.0
+sphinx-reredirects==0.1.3
+sphinx-sitemap==2.6.0
+sphinx_design==0.5.0
+sphinxcontrib-httpdomain==1.8.1
+sphinxcontrib-httpexample==1.1
+# sphinxcontrib-mermaid==0.9.2  # See https://github.com/mgaitan/sphinxcontrib-mermaid/issues/137
+sphinxcontrib-video==0.2.0
+sphinxext-opengraph==0.9.1
+vale==3.7.1

requirements-initial.txt

@@ -1,5 +1,5 @@
 # requirements-initial.txt
 # From https://dist.plone.org/release/6-latest/constraints.txt
-pip==24.0
-setuptools==69.5.1
-wheel==0.43.0
+pip==24.2
+setuptools==74.0.0
+wheel==0.44.0

styles/Vocab/Plone/accept.txt → styles/config/vocabularies/Plone/accept.txt

@@ -13,23 +13,28 @@ Barceloneta
 [Bb]oolean
 buildout
 cacheable
+Code of Conduct
 docstrings
 doctest
 Docutils
 folderish
 fieldset
+Gantt
 getter
 Graphviz
 JavaScript
 jQuery
+Kitchen Sink
 Mockup
 multilanguage
 multiversion
+MyST
 Netlify
 npm
 nvm
 Pastanaga
 Plone
+Plone Sphinx Theme
 pluggab(le|ility)
 programatically
 [Pp]ortlet