Documentation coverage builder, part 1.

diff --git a/Doc/Makefile b/Doc/Makefile
index d893b79ab663e59ade87c74fd594f42baa8995f5..e94be8160d6972bb3ae4cd8783a776969fd8acbd 100644 (file)
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -12,7 +12,7 @@ PAPER        =
 ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees -D latex_paper_size=$(PAPER) \
                 $(SPHINXOPTS) . build/$(BUILDER)
 
-.PHONY: help checkout update build html web htmlhelp clean
+.PHONY: help checkout update build html web htmlhelp clean coverage
 
 help:
        @echo "Please use \`make <target>' where <target> is one of"
@@ -22,6 +22,7 @@ help:
        @echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
        @echo "  changes   to make an overview over all changed/added/deprecated items"
        @echo "  linkcheck to check all external links for integrity"
+       @echo "  coverage  to check documentation coverage for library and C API"
 
 checkout:
        @if [ ! -d tools/sphinx ]; then \
@@ -74,9 +75,13 @@ changes: build
 
 linkcheck: BUILDER = linkcheck
 linkcheck: build
-       @echo "Link check complete; look for any errors in the above output "\
+       @echo "Link check complete; look for any errors in the above output " \
              "or in build/$(BUILDER)/output.txt"
 
+coverage: BUILDER = coverage
+coverage: build
+       @echo "Coverage finished; see c.txt and python.txt in build/coverage"
+
 clean:
        -rm -rf build/*
        -rm -rf tools/sphinx

diff --git a/Doc/README.txt b/Doc/README.txt
index 087efd594d2311a77101d9cfaecc66341ff25082..dfb3d58f2718f540c875a68c0fbbf5f4ebaed2e8 100644 (file)
--- a/Doc/README.txt
+++ b/Doc/README.txt
@@ -59,6 +59,9 @@ Available make targets are:
    deprecated items in the current version. This is meant as a help for the
    writer of the "What's New" document.
 
+ * "coverage", which builds a coverage overview for standard library modules
+   and C API.
+
 A "make update" updates the Subversion checkouts in `tools/`.
 
 

diff --git a/Doc/conf.py b/Doc/conf.py
index e19895063d350f3d0e2c537b160120dbdb9b479e..bca1bef4d4e95b7563f3d8d220c95ce801a93122 100644 (file)
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -13,7 +13,7 @@ sys.path.append('tools/sphinxext')
 # General configuration
 # ---------------------
 
-extensions = ['sphinx.addons.refcounting']
+extensions = ['sphinx.addons.refcounting', 'sphinx.addons.coverage']
 
 # General substitutions.
 project = 'Python'
@@ -139,3 +139,39 @@ latex_preamble = r'''
 
 # Documents to append as an appendix to all manuals.
 latex_appendices = ['glossary', 'about', 'license', 'copyright']
+
+# Options for the coverage checker
+# --------------------------------
+
+# The coverage checker will ignore all modules/functions/classes whose names
+# match any of the following regexes (using re.match).
+coverage_ignore_modules = [
+    r'[T|t][k|K]',
+    r'Tix',
+    r'distutils.*',
+]
+
+coverage_ignore_functions = [
+    'test($|_)',
+]
+
+coverage_ignore_classes = [
+]
+
+# Glob patterns for C source files for C API coverage, relative to this directory.
+coverage_c_path = [
+    '../Include/*.h',
+]
+
+# Regexes to find C items in the source files.
+coverage_c_regexes = {
+    'cfunction': (r'^PyAPI_FUNC\(.*\)\s+([^_][\w_]+)'),
+    'data': (r'^PyAPI_DATA\(.*\)\s+([^_][\w_]+)'),
+    'macro': (r'^#define ([^_][\w_]+)\(.*\)[\s|\\]'),
+}
+
+# The coverage checker will ignore all C items whose names match these regexes
+# (using re.match) -- the keys must be the same as in coverage_c_regexes.
+coverage_ignore_c_items = {
+#    'cfunction': [...]
+}