From 19945fd67b0228b78534bba3438f0ee7690c9adf Mon Sep 17 00:00:00 2001
From: Hynek Schlawack <hs@ox.cx>
Date: Sun, 14 Jan 2024 07:31:44 +0100
Subject: [PATCH] Stop polluting dev env with docs deps

---
 .github/CONTRIBUTING.md | 22 +++++++++++++---------
 pyproject.toml          |  2 +-
 tox.ini                 | 23 ++++++++++++++---------
 3 files changed, 28 insertions(+), 19 deletions(-)

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index af5d8d1..21d8ad2 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -65,7 +65,7 @@ $ git clone https://github.com/YOU/service-identity.git
 >   Yes, you can work on `main` in your fork and submit pull requests.
 >   But this will *inevitably* lead to you not being able to synchronize your fork with upstream and having to start over.
 
-Change into the newly created directory and after activating a virtual environment, install an editable version of *service-identity* along with its tests and docs requirements:
+Change into the newly created directory and after activating a virtual environment, install an editable version of *service-identity* along with its tests requirements:
 
 ```console
 $ cd service-identity
@@ -79,13 +79,21 @@ At this point,
 $ python -Im pytest
 ```
 
-should work and pass, as should:
+When working on the documentation, use:
 
 ```console
-$ cd docs
-$ make html
+$ tox run -e docs-watch
 ```
 
+... to watch your files and automatically rebuild when a file changes.
+And use:
+
+```console
+$ tox run -e docs
+```
+
+... to build it once and run our doctests.
+
 The built documentation can then be found in `docs/_build/html/`.
 
 ---
@@ -102,7 +110,6 @@ This is not strictly necessary, because our [*tox*] file contains an environment
 $ pre-commit run --all-files
 ```
 
-and our CI has integration with [pre-commit.ci](https://pre-commit.ci).
 But it's way more comfortable to run it locally and catch avoidable errors before pushing them to GitHub.
 
 
@@ -149,9 +156,6 @@ But it's way more comfortable to run it locally and catch avoidable errors befor
 
 - To run the test suite, all you need is a recent [*tox*].
   It will ensure the test suite runs with all dependencies against all Python versions just as it will in our [CI].
-  If you lack some Python versions, you can can always limit the environments like `tox -e py38,py39`, or make it a non-failure using `tox --skip-missing-interpreters`.
-
-  In that case you should look into [*asdf*](https://asdf-vm.com) or [*pyenv*](https://github.com/pyenv/pyenv), which make it very easy to install many different Python versions in parallel.
 - Write [good test docstrings](https://jml.io/pages/test-docstrings.html).
 - If you've changed or added public APIs, please update our type stubs (files ending in `.pyi`).
 
@@ -175,7 +179,7 @@ But it's way more comfortable to run it locally and catch avoidable errors befor
 
   ## Header of New Top Section
 
-  ###  Header of New Section
+  ### Header of New Section
 
   First line of new section.
   ```
diff --git a/pyproject.toml b/pyproject.toml
index 911a510..abacb5b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -38,7 +38,7 @@ idna = ["idna"]
 tests = ["coverage[toml]>=5.0.2", "pytest"]
 docs = ["sphinx", "furo", "myst-parser", "sphinx-notfound-page", "pyOpenSSL"]
 mypy = ["mypy", "types-pyOpenSSL", "idna"]
-dev = ["service-identity[tests,mypy,docs,idna]", "pyOpenSSL"]
+dev = ["service-identity[tests,mypy,idna]", "pyOpenSSL"]
 
 [project.urls]
 Documentation = "https://service-identity.readthedocs.io/"
diff --git a/tox.ini b/tox.ini
index 49fc423..13b20a0 100644
--- a/tox.ini
+++ b/tox.ini
@@ -28,6 +28,16 @@ commands =
     py312-pyopenssl-latest-idna: coverage run -m pytest --doctest-modules --doctest-glob='*.rst' {posargs}
 
 
+[testenv:coverage-report]
+# keep in-sync with .python-version-default
+base_python = py312
+deps = coverage[toml]>=5.0.2
+skip_install = true
+commands =
+    coverage combine
+    coverage report
+
+
 [testenv:lint]
 skip_install = true
 deps = pre-commit
@@ -64,12 +74,7 @@ commands =
         src \
         docs
 
-
-[testenv:coverage-report]
-# keep in-sync with .python-version-default
-base_python = py312
-deps = coverage[toml]>=5.0.2
-skip_install = true
-commands =
-    coverage combine
-    coverage report
+[testenv:docs-linkcheck]
+base_python = {[testenv:docs]base_python}
+extras = {[testenv:docs]extras}
+commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees docs docs/_build/html