Improve doc tooling

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
 

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:

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 @@
     '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 @@
 
 # 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 @@
 # 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 @@
 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)

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

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

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

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

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}