Add documentation testing (#902)

* Test the documentation builds locally

* Test the documentation builds in CI

* Fix the lone documentation build warning

* Update `AUTHORS` and `changelog.rst`

.github/workflows/tests.yml

@@ -11,6 +11,7 @@ on:
       - "setup.*"
       - "src/**/*"
       - "tests/*.py"
+      - "docs/**/*"
 
 jobs:
   lint:
@@ -56,3 +57,20 @@ jobs:
         run: python -m pip install tox
       - name: Test
         run: python -m tox -e py
+
+  docs:
+    name: Test documentation builds
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+        with:
+          ref: ${{ github.event.inputs.branch }}
+      - name: Use Python 3.10
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.10"
+      - name: Install test dependencies
+        run: python -m pip install tox
+      - name: Test
+        run: python -m tox -e docs

AUTHORS

@@ -17,6 +17,7 @@ Gary van der Merwe <garyvdm@garyvdm.localdomain>
 Gora Khargosh <gora.khargosh@gmail.com>
 Hannu Valtonen <hannu.valtonen@ohmu.fi>
 Jesse Printz <jesse@jonypawks.net>
+Kurt McKee <contactme@kurtmckee.org>
 Léa Klein <lklein@nuxeo.com>
 Luke McCarthy <luke@iogopro.co.uk>
 Lukáš Lalinský <lalinsky@gmail.com>

changelog.rst

@@ -8,8 +8,8 @@ Changelog
 
 2022-xx-xx • `full history <https://github.com/gorakhargosh/watchdog/compare/v2.1.9...HEAD>`__
 
-- 
-- Thanks to our beloved contributors: @
+- [documentation] HTML documentation builds are now tested for errors.
+- Thanks to our beloved contributors: @kurtmckee
 
 2.1.9
 ~~~~~

docs/source/installation.rst

@@ -14,7 +14,7 @@ Installing from PyPI using pip
     $ python -m pip install -U |project_name|
 
     # or to install the watchmedo utility:
-    $ python -m pip install -U |project_name|[watchmedo]
+    $ python -m pip install -U |project_name|\[watchmedo]
 
 Installing from source tarballs
 -------------------------------

requirements-tests.txt

@@ -6,3 +6,4 @@ flaky
 pytest
 pytest-cov
 pytest-timeout
+sphinx

tox.ini

@@ -1,5 +1,5 @@
 [tox]
-envlist = py{311,310,39,38,37,36,py3}
+envlist = py{311,310,39,38,37,36,py3}, docs
 skip_missing_interpreters = True
 
 [testenv]
@@ -15,3 +15,10 @@ deps =
     -r requirements-tests.txt
 commands =
     python -m flake8 docs tools src tests setup.py
+
+[testenv:docs]
+usedevelop = true
+deps =
+    -r requirements-tests.txt
+commands =
+    sphinx-build -aEWb html docs/source docs/build/html