Merge pull request #40 from plone/docs-override-conf-opts

Add documentation for how to override build configuration options

docs/guides/contribute.md

@@ -64,6 +64,34 @@ make kitchen-sink-update
 ```
 
 
+(override-build-configuration-options)=
+
+### Override build configuration options
+
+Both Sphinx and vale support overriding configuration options.
+The following examples serve as tips for spotting mistakes in your documentation when you have too many errors or warnings.
+
+In Sphinx, you can use the `SPHINXOPTS` environment variable to set [configuration options](https://www.sphinx-doc.org/en/master/usage/configuration.html) of [`sphinx-build`](https://www.sphinx-doc.org/en/master/man/sphinx-build.html).
+Syntax is in the following form.
+
+```shell
+make SPHINXOPTS="OPTION VALUE" BUILDER
+```
+
+The following example shows how to clean then build a live HTML preview of the documentation while suppressing syntax highlighting failures.
+
+```shell
+make SPHINXOPTS="-D suppress_warnings=['misc.highlighting_failure']" clean livehtml
+```
+
+You can also pass options to vale in the `VALEOPTS` environment variable.
+In the following example, vale will not return a non-zero exit code when there are errors and will display warnings or errors only, not suggestions.
+
+```shell
+make vale VALEOPTS="--no-exit --minAlertLevel='warning'"
+```
+
+
 ## Edit the theme
 
 You can edit the Plone Sphinx Theme's layout, content, styles, and JavaScripts.

news/40.documentation

@@ -0,0 +1 @@
+Add documentation for how to override build configuration options. @stevepiercy