Replace sphinxcontrib.spelling with Vale.

See plone#1347

Author: stevepiercy

.gitignore

@@ -7,6 +7,7 @@
 # Generated files
 pyvenv.cfg
 /_build
+/styles/Microsoft
 
 # symlinked from submodule
 docs/volto

.vale.ini

@@ -0,0 +1,10 @@
+StylesPath = styles
+
+MinAlertLevel = suggestion
+
+Vocab = Base,Plone
+
+Packages = Microsoft
+
+[*]
+BasedOnStyles = Vale, Microsoft

Makefile

@@ -16,7 +16,7 @@ PAPEROPT_letter = -D latex_paper_size=letter
 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 -L $(DOCS_DIR) -type d \( -path $(DOCS_DIR)/plone.restapi/lib/* -o  -path $(DOCS_DIR)"/plone.restapi/performance/*" \) -prune -false -o -type f -name "*.md" -print)
 
 # Add the following 'help' target to your Makefile
 # And add help text after each target name starting with '\#\#'
@@ -194,12 +194,12 @@ linkcheckbroken: deps  ## Run linkcheck and show only broken links
 	@echo "Link check complete; look for any errors in the above output " \
 		"or in $(BUILDDIR)/linkcheck/ ."
 
-.PHONY: spellcheck
-spellcheck: deps  ## Run spellcheck
-	cd $(DOCS_DIR) && LANGUAGE=$* $(SPHINXBUILD) -b spelling -j 4 $(ALLSPHINXOPTS) $(BUILDDIR)/spellcheck/$*
+.PHONY: vale
+vale: deps  ## Run Vale style, grammar, and spell checks
+	vale sync
+	vale --no-wrap $(VALEFILES)
 	@echo
-	@echo "Spellcheck is finished; look for any errors in the above output " \
-		" or in $(BUILDDIR)/spellcheck/ ."
+	@echo "Vale is finished; look for any errors in the above output."
 
 .PHONY: html_meta
 html_meta: deps  ## Add meta data headers to all Markdown pages
@@ -212,7 +212,7 @@ doctest: deps
 	      "results in $(BUILDDIR)/doctest/output.txt."
 
 .PHONY: test
-test: clean linkcheckbroken spellcheck  ## Clean docs build, then run linkcheckbroken, spellcheck
+test: clean linkcheckbroken vale ## Clean docs build, then run linkcheckbroken and vale
 
 .PHONY: deploy
 deploy: clean html
@@ -241,4 +241,4 @@ storybook:
 	cd submodules/volto && yarn && yarn build-storybook -o ../../_build/html/storybook
 
 .PHONY: all
-all: clean spellcheck linkcheck html  ## Clean docs build, then run linkcheck and spellcheck, and build html
+all: clean vale linkcheck html  ## Clean docs build, then run vale and linkcheck, and build html

docs/conf.py

@@ -51,7 +51,6 @@
     "sphinx_sitemap",
     "sphinxcontrib.httpdomain",  # plone.restapi
     "sphinxcontrib.httpexample",  # plone.restapi
-    "sphinxcontrib.spelling",
     "sphinxext.opengraph",
     "sphinx.ext.viewcode",  # plone.api
     "sphinx.ext.autosummary",  # plone.api
@@ -96,10 +95,6 @@
 linkcheck_timeout = 10
 linkcheck_retries = 2
 
-# This is our wordlist with known words, like Github or Plone ...
-spelling_word_list_filename = "spelling_wordlist.txt"
-spelling_ignore_pypi_package_names = True
-
 # The suffix of source filenames.
 source_suffix = {
     ".md": "markdown",

docs/contributing/authors.md

@@ -4,7 +4,7 @@ myst:
     "description": "Authors' guide to writing Plone Documentation. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors."
     "property=og:description": "Authors' guide to writing Plone Documentation. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors."
     "property=og:title": "Authors Guide"
-    "keywords": "Plone, Documentation, SEO, meta, exercises, solutions, spellcheck, linkcheck, lexer"
+    "keywords": "Plone, Documentation, SEO, meta, Vale, spell, grammar, style, check, linkcheck, lexer"
 ---
 
 (authors-guide-label)=
@@ -34,7 +34,7 @@ myst:
     "description": "Authors' guide to writing Plone Documentation. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors."
     "property=og:description": "Authors' guide to writing Plone Documentation. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors."
     "property=og:title": "Authors Guide"
-    "keywords": "Plone, Documentation, SEO, meta, spellcheck, linkcheck, lexer"
+    "keywords": "Plone, Documentation, SEO, meta, Vale, spell, grammar, style, check, linkcheck, lexer"
 ---
 ```
 
@@ -44,7 +44,7 @@ This renders in the HTML `<head>` section as follows.
 <meta content="Authors' guide to writing Plone Documentation. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors." name="description" />
 <meta content="Authors' guide to writing Plone Documentation. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors." property="og:description" />
 <meta content="Authors Guide" property="og:title" />
-<meta content="Plone, Documentation, SEO, meta, spellcheck, linkcheck, lexer" name="keywords" />
+<meta content="Plone, Documentation, SEO, meta, Vale, spell, grammar, style, check, linkcheck, lexer" name="keywords" />
 ```
 
 Additional {term}`Open Graph` metadata is implemented through the Sphinx extension [`sphinxext-opengraph`](https://github.com/wpilibsuite/sphinxext-opengraph) and the [MyST `html_meta` directive](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#setting-html-metadata), which resolves to the [Docutils `meta` directive](https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata).
@@ -75,25 +75,23 @@ Open `/_build/html/index.html` in a web browser.
 
 (authors-english-label)=
 
-### American English Spelling, Grammar, and Syntax
+### American English Spelling, Grammar, and Syntax, and Style Guide
 
-Spellings are enforced through [`spellcheck`](https://sphinxcontrib-spelling.readthedocs.io/en/latest/index.html).
-We use the locale `en_US`.
+Spellings are enforced through [`Vale`](https://vale.sh/).
+Plone uses American English.
 
-Spelling is configured in {file}`Makefile`, {file}`docs/conf.py`, and {file}`docs/spelling_wordlist.txt`.
+Spelling is configured in {file}`Makefile`, {file}`.vale.ini`, and in files in `styles/Vocab/Plone/`.
 
-Authors should add new words and proper names using correct casing to {file}`docs/spelling_wordlist.txt`, sorted alphabetically.
+Authors should add new words and proper names using correct casing to {file}`styles/Vocab/Plone/accept.txt`, sorted alphabetically and case-insensitive.
 
-See [default settings and configuration options](https://sphinxcontrib-spelling.readthedocs.io/en/latest/customize.html).
+Vale also provides English grammar and syntax checking, as well as a Style Guide.
 
-To validate spelling, run the following command.
+To perform all these checks, run the following command.
 
 ```shell
-make spellcheck
+make vale
 ```
 
-Open `/_build/spellcheck/` for misspellings.
-
 Because it is difficult to automate good English grammar and syntax, we do not strictly enforce it.
 We also understand that contributors might not be fluent in English.
 We encourage contributors to make a reasonable effort, and to seek help from community members who are fluent in English.

docs/contributing/index.md

@@ -153,7 +153,7 @@ This section describes how to make contributions to files in the `plone/document
     ```
 
     ```{note}
-    Eventually the `spellcheck` build will be required, but not at this time.
+    Eventually the `vale` build will be required, but not at this time.
     We welcome improvements to the dictionary.
     ```
 

docs/contributing/setup-build.md

@@ -4,7 +4,7 @@ myst:
     "description": "How to set up the Plone Documentation locally"
     "property=og:description": "How to set up the Plone Documentation locally"
     "property=og:title": "Building and Checking the Quality of Documentation"
-    "keywords": "setup, build, documentation, quality, development, spellcheck, linkcheck"
+    "keywords": "setup, build, documentation, quality, development, Vale, spell, grammar, style, check, linkcheck"
 ---
 
 (setup-build-label)=
@@ -18,25 +18,40 @@ This document covers how to build the Plone Documentation and check it for quali
 
 ## Installation
 
-Optionally install [Enchant](https://abiword.github.io/enchant/) to check spelling.
+Installation of Plone 6 Documentation includes pre-requisites and the repository itself.
 
-```{todo}
-Due to the complexity of installing Enchant and the inability of its Python bindings in [pyenchant to properly spellcheck hyphenated words](https://github.com/pyenchant/pyenchant/issues/286) through the Sphinx extension [`sphinxcontrib-spelling`](https://github.com/sphinx-contrib/spelling), the [Plone Documentation Team](https://github.com/orgs/plone/teams/documentation-team/members) is [evaluating Vale as a replacement](https://github.com/plone/documentation/issues/1347).
-```
 
+(setup-build-installation-vale-label)=
 
-**macOS**
+### Vale
 
-```shell
-brew install enchant
-```
+Vale is a linter for narrative text.
+It checks spelling, English grammar, and style guides.
+Plone documentation uses a custom spelling dictionary, with accepted and rejected spellings in `styles/Vocab/Plone`.
 
-**Ubuntu**
+Use your operating system's package manager to [install Vale](https://vale.sh/docs/vale-cli/installation/).
 
-```shell
-sudo apt-get install enchant
+Vale also has [integrations](https://vale.sh/docs/integrations/guide/) with various IDEs.
+
+-   [JetBrains](https://vale.sh/docs/integrations/jetbrains/)
+-   [Vim](https://github.com/dense-analysis/ale)
+-   [VS Code](https://github.com/errata-ai/vale-vscode)
+
+Plone documentation uses a file located at the root of the repository, `.vale.ini`, to configure Vale.
+This file allows overriding rules or changing their severity.
+
+The Plone Documentation Team selected the [Microsoft Writing Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/) for its ease of use—especially for non-native English readers and writers—and attention to non-technical audiences. 
+
+```{note}
+More corrections to spellings and Vale's configuration are welcome by submitting a pull request.
+This is an easy way to become a contributor to Plone.
 ```
 
+
+(setup-build-installation-clone-plone-documentation-label)=
+
+### Clone `plone/documentation`
+
 Clone the Plone Documentation repository, and change your working directory into the cloned project.
 Then with a single command using `Makefile`, create a Python virtual environment, install project dependencies, pull in Volto documentation as a git submodule, build the docs, and view the results in a web browser by opening `/_build/html/index.html`.
 
@@ -46,11 +61,6 @@ cd documentation
 make html
 ```
 
-```{note}
-If you are using an M1 Mac to build the documentation, there is currently [an issue with pyenchant](https://github.com/pyenchant/pyenchant/issues/265) that throws an error that the enchant library can't be found.
-This happens for example if you install Python 3 with `pyenv` in the default M1 architecture (aarch64), so without following instructions to use Rosetta2 x86 emulation.
-A workaround until pyenchant is fixed is to run `export PYENCHANT_LIBRARY_PATH=/opt/homebrew/lib/libenchant-2.dylib` in the terminal session before you execute `make html`.
-```
 
 (setup-build-available-documentation-builds-label)=
 
@@ -101,16 +111,16 @@ make linkcheck
 Open `/_build/linkcheck/output.txt` for a list of broken links.
 
 
-### `spellcheck`
+### `vale`
 
-`spellcheck` checks the spelling of words.
+`vale` checks for American English spelling, grammar, syntax, and the Microsoft Developer Style Guide.
 See {ref}`authors-english-label` for configuration.
 
 ```shell
-make spellcheck
+make vale
 ```
 
-Open `/_build/spellcheck/` for misspellings.
+See the output on the console for suggestions.
 
 
 ### `html_meta`

docs/contributing/writing-docs-guide.md

@@ -286,7 +286,6 @@ We use several extensions to enhance the presentation of Plone documentation.
 -   [`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.restapi/docs/source/index`.
--   [`sphinxcontrib.spelling`](https://sphinxcontrib-spelling.readthedocs.io/en/latest/) provides spell checking. 
 -   [`sphinxext.opengraph`](https://pypi.org/project/sphinxext-opengraph/) generates [OpenGraph metadata](https://ogp.me/).
 -   [`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.api/index`.
@@ -321,5 +320,7 @@ This will greatly improve the editing and maintenance of your documentation.
 
 Because it is difficult to automate good English grammar and syntax, we do not strictly enforce it.
 We also understand that contributors might not be fluent in English.
+We use [Vale](https://vale.sh/) as a tool to check spelling, grammar, and style.
+Vale can help contributors improve their writing. 
 We encourage contributors to make a reasonable effort, and to seek help from community members who are fluent in English.
 Please ask!

requirements.txt

@@ -13,5 +13,4 @@ sphinx-sitemap
 sphinx-togglebutton
 sphinxcontrib.httpdomain  # plone.restapi
 sphinxcontrib.httpexample  # plone.restapi
-sphinxcontrib-spelling
 sphinxext-opengraph