From f2a778b3aa18de0bd43b1ba1a144d16faa53b8a2 Mon Sep 17 00:00:00 2001
From: Ned Batchelder <ned@nedbatchelder.com>
Date: Sun, 11 Aug 2019 16:06:00 -0400
Subject: Improve doc tooling

---
 MANIFEST.in             |  2 +-
 Makefile                | 10 +++++-----
 doc/conf.py             | 13 ++++++++++---
 doc/requirements.pip    |  4 ++--
 requirements/dev.pip    |  4 +++-
 requirements/pytest.pip |  1 -
 requirements/tox.pip    |  2 +-
 tox.ini                 |  3 ++-
 8 files changed, 24 insertions(+), 15 deletions(-)

diff --git a/MANIFEST.in b/MANIFEST.in
index 32cc1809..b30f8851 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -34,7 +34,7 @@ exclude ci/*.token
 recursive-include coverage/fullcoverage *.py
 recursive-include coverage/ctracer *.c *.h
 
-recursive-include doc conf.py *.pip *.rst *.txt *.png
+recursive-include doc *.py *.pip *.rst *.txt *.png
 recursive-include doc/_static *.*
 prune doc/_build
 
diff --git a/Makefile b/Makefile
index 6dc0cce0..6810fdeb 100644
--- a/Makefile
+++ b/Makefile
@@ -114,21 +114,21 @@ uninstall:
 
 # Documentation
 
-SPHINXBUILD = sphinx-build
+SPHINXBUILD = .tox/doc/bin/sphinx-build
 SPHINXOPTS = -a -E doc
 WEBHOME = ~/web/stellated/
 WEBSAMPLE = $(WEBHOME)/files/sample_coverage_html
 WEBSAMPLEBETA = $(WEBHOME)/files/sample_coverage_html_beta
 
 docreqs:
-	pip install -r doc/requirements.pip
+	tox -q -e doc --notest
 
-dochtml:
-	PYTHONPATH=$(CURDIR) $(SPHINXBUILD) -b html $(SPHINXOPTS) doc/_build/html
+dochtml: docreqs
+	$(SPHINXBUILD) -b html $(SPHINXOPTS) doc/_build/html
 	@echo
 	@echo "Build finished. The HTML pages are in doc/_build/html."
 
-docspell:
+docspell: docreqs
 	$(SPHINXBUILD) -b spelling $(SPHINXOPTS) doc/_spell
 
 publish:
diff --git a/doc/conf.py b/doc/conf.py
index 28ec17f4..836f77c9 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -2,7 +2,8 @@
 # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
 # For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
 
-#
+"""Sphinx configuration."""
+
 # coverage.py documentation build configuration file, created by
 # sphinx-quickstart on Wed May 13 22:18:33 2009.
 #
@@ -14,7 +15,7 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import os
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -33,6 +34,7 @@ extensions = [
     'sphinx.ext.todo',
     'sphinx.ext.ifconfig',
     'sphinxcontrib.spelling',
+    'sphinx.ext.intersphinx',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -49,7 +51,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'Coverage.py'
-copyright = u'2009\N{EN DASH}2019, Ned Batchelder.'     # CHANGEME
+copyright = u'2009\N{EN DASH}2019, Ned Batchelder.'     # CHANGEME  # pylint: disable=redefined-builtin
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -97,6 +99,10 @@ pygments_style = 'sphinx'
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    }
+
 # -- Options for HTML output ---------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
@@ -189,6 +195,7 @@ autoclass_content = "class"
 prerelease = bool(max(release).isalpha())
 
 def setup(app):
+    """Configure Sphinx"""
     app.add_stylesheet('coverage.css')
     app.add_config_value('prerelease', False, 'env')
     print("** Prerelease = %r" % prerelease)
diff --git a/doc/requirements.pip b/doc/requirements.pip
index 7c9f9067..3f864737 100644
--- a/doc/requirements.pip
+++ b/doc/requirements.pip
@@ -4,6 +4,6 @@
 
 doc8==0.8.0
 pyenchant==2.0.0
-sphinx==2.0.1
-sphinxcontrib-spelling==4.2.1
+sphinx==2.1.2
+sphinxcontrib-spelling==4.3.0
 sphinx_rtd_theme==0.4.3
diff --git a/requirements/dev.pip b/requirements/dev.pip
index 9b92d20a..2010dcc0 100644
--- a/requirements/dev.pip
+++ b/requirements/dev.pip
@@ -4,9 +4,11 @@
 # Requirements for doing local development work on coverage.py.
 # https://requires.io/github/nedbat/coveragepy/requirements/
 
-pip==19.1.1
+pip==19.2.1
 virtualenv==16.5.0
 
+pluggy==0.12.0
+
 # PyPI requirements for running tests.
 -r tox.pip
 -r pytest.pip
diff --git a/requirements/pytest.pip b/requirements/pytest.pip
index 3c582310..30799efa 100644
--- a/requirements/pytest.pip
+++ b/requirements/pytest.pip
@@ -4,7 +4,6 @@
 # The pytest specifics used by coverage.py
 
 pytest==4.6.2
-pluggy>=0.7         # pytest needs this, but pip doesn't understand
 pytest-xdist==1.28.0
 flaky==3.5.3
 mock==3.0.5
diff --git a/requirements/tox.pip b/requirements/tox.pip
index e4ff4031..6eb32612 100644
--- a/requirements/tox.pip
+++ b/requirements/tox.pip
@@ -2,6 +2,6 @@
 # For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
 
 # The version of tox used by coverage.py
-tox==3.9.0
+tox==3.13.2
 # Adds env recreation on requirements file changes.
 tox-battery==0.5.1
diff --git a/tox.ini b/tox.ini
index 6f539a10..33e3309a 100644
--- a/tox.ini
+++ b/tox.ini
@@ -61,9 +61,10 @@ commands =
 [testenv:lint]
 deps =
     -r requirements/dev.pip
+    -r doc/requirements.pip
 
 setenv =
-    LINTABLE = coverage tests igor.py setup.py __main__.py
+    LINTABLE = coverage tests doc igor.py setup.py __main__.py
 
 commands =
     python -m tabnanny {env:LINTABLE}
-- 
cgit v1.2.1