From 170482809864d7b5cd8c3e2584074e3e5de808c0 Mon Sep 17 00:00:00 2001
From: Georg Brandl <georg@python.org>
Date: Sat, 23 Feb 2008 18:47:04 +0000
Subject: [PATCH] Documentation coverage builder, part 1.

---
 Doc/Makefile   |  9 +++++++--
 Doc/README.txt |  3 +++
 Doc/conf.py    | 38 +++++++++++++++++++++++++++++++++++++-
 3 files changed, 47 insertions(+), 3 deletions(-)

diff --git a/Doc/Makefile b/Doc/Makefile
index d893b79ab66..e94be8160d6 100644
--- 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 087efd594d2..dfb3d58f271 100644
--- 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 e19895063d3..bca1bef4d4e 100644
--- 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': [...]
+}