Documentation coverage builder, part 1.
diff --git a/Doc/Makefile b/Doc/Makefile
index d893b79..e94be81 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -12,7 +12,7 @@
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 @@
@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 @@
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 087efd5..dfb3d58 100644
--- a/Doc/README.txt
+++ b/Doc/README.txt
@@ -59,6 +59,9 @@
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 e198950..bca1bef 100644
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -13,7 +13,7 @@
# General configuration
# ---------------------
-extensions = ['sphinx.addons.refcounting']
+extensions = ['sphinx.addons.refcounting', 'sphinx.addons.coverage']
# General substitutions.
project = 'Python'
@@ -139,3 +139,39 @@
# 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': [...]
+}