Check for dead links in documentation

.github/workflows/docs.yml

@@ -1,7 +1,8 @@
-name: Build documentation
+name: Check documentation
 on: [push, pull_request]
 jobs:
   docs:
+    name: Build documentation & check links
     runs-on: ubuntu-latest
     steps:
       - uses: actions/[email protected]
@@ -11,8 +12,11 @@ jobs:
       - run: |
           pip install --constraint=.github/workflows/constraints.txt pip
           pip install --constraint=.github/workflows/constraints.txt nox
-      - run: nox --force-color --session=docs
+      - name: Build documentation
+        run: nox --force-color --session=docs
       - uses: actions/upload-artifact@v2
         with:
           name: docs
           path: docs/_build
+      - name: Check links
+        run: nox --force-color --session=linkcheck

CONTRIBUTING.rst

@@ -67,7 +67,7 @@ and set up `continuous integration`_.
 .. _Nox: https://nox.thea.codes/
 .. _nox-poetry: https://nox-poetry.readthedocs.io/
 .. _Github: https://github.com/cjolowicz/cookiecutter-hypermodern-python
-.. _continuous integration: https://github.com/cjolowicz/cookiecutter-hypermodern-python/#continuous-integration
+.. _continuous integration: https://cookiecutter-hypermodern-python.readthedocs.io/en/stable/quickstart.html#continuous-integration
 
 
 How to test the project

docs/conf.py

@@ -22,3 +22,12 @@
     "fixed_sidebar": "true",
     "sidebar_width": "250px",
 }
+linkcheck_ignore = [
+    "codeofconduct.html",
+    "https://github.com/PyCQA/flake8-bugbear#",
+    "https://github.com/peterjc/flake8-rst-docstrings#",
+    "https://github.com/pre-commit/pre-commit-hooks#",
+    "https://github.com/pycqa/pep8-naming#",
+    "https://github.com/terrencepreilly/darglint#",
+    "https://github.com/PyCQA/mccabe#",
+]

docs/guide.rst

@@ -529,14 +529,14 @@ The test suite is `declared as a package`__,
 and mirrors the source layout of the package under test.
 The file ``test_main.py`` contains tests for the ``__main__`` module.
 
-__ http://doc.pytest.org/en/latest/goodpractices.html#tests-outside-application-code
+__ https://docs.pytest.org/en/latest/explanation/goodpractices.html#choosing-a-test-layout-import-rules
 
 Initially, the test suite contains a single test case,
 checking whether the program exits with a status code of zero.
 It also provides a `test fixture`_ using `click.testing.CliRunner`_,
 a helper class for invoking the program from within tests.
 
-.. _test fixture: https://docs.pytest.org/en/latest/fixture.html
+.. _test fixture: https://docs.pytest.org/en/latest/explanation/fixtures.html#about-fixtures
 .. _click.testing.CliRunner: https://click.palletsprojects.com/en/7.x/testing/
 
 For details on how to run the test suite,
@@ -1840,7 +1840,7 @@ Here is an example of a function documented in Google style:
            The sum of the arguments.
        """
 
-.. _Google docstring style: https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings.
+.. _Google docstring style: https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings
 
 
 flake8-rst-docstrings

noxfile.py

@@ -6,6 +6,9 @@
 from nox.sessions import Session
 
 
+nox.options.sessions = ["linkcheck"]
+
+
 @nox.session
 def docs(session: Session) -> None:
     """Build the documentation."""
@@ -24,3 +27,17 @@ def docs(session: Session) -> None:
         session.run("sphinx-autobuild", *args)
     else:
         session.run("sphinx-build", *args)
+
+
+@nox.session
+def linkcheck(session: Session) -> None:
+    """Build the documentation."""
+    args = session.posargs or ["-b", "linkcheck", "-W", "--keep-going", "docs", "docs/_build"]
+
+    builddir = Path("docs", "_build")
+    if builddir.exists():
+        shutil.rmtree(builddir)
+
+    session.install("-r", "docs/requirements.txt")
+
+    session.run("sphinx-build", *args)