diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 1cc1b3bef..123af2da3 100644 --- a/.github/workflows/docs.yml +++ b/.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/checkout@v2.3.4 @@ -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 diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 497f2f3ac..4388502eb 100644 --- a/CONTRIBUTING.rst +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index 3f422bc6e..4ab7574be 100644 --- a/docs/conf.py +++ b/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#", +] diff --git a/docs/guide.rst b/docs/guide.rst index 35611087d..ef50b1777 100644 --- a/docs/guide.rst +++ b/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 diff --git a/noxfile.py b/noxfile.py index abefc92e3..c98829bfc 100644 --- a/noxfile.py +++ b/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)