[Python-checkins] r61004 - python/trunk/Doc/Makefile python/trunk/Doc/README.txt python/trunk/Doc/conf.py

[georg.brandl]

Author: georg.brandl
Date: Sat Feb 23 19:47:04 2008
New Revision: 61004

Modified:
   python/trunk/Doc/Makefile
   python/trunk/Doc/README.txt
   python/trunk/Doc/conf.py
Log:
Documentation coverage builder, part 1.


Modified: python/trunk/Doc/Makefile
==============================================================================
--- python/trunk/Doc/Makefile	(original)
+++ python/trunk/Doc/Makefile	Sat Feb 23 19:47:04 2008
@@ -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

Modified: python/trunk/Doc/README.txt
==============================================================================
--- python/trunk/Doc/README.txt	(original)
+++ python/trunk/Doc/README.txt	Sat Feb 23 19:47:04 2008
@@ -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/`.
 
 

Modified: python/trunk/Doc/conf.py
==============================================================================
--- python/trunk/Doc/conf.py	(original)
+++ python/trunk/Doc/conf.py	Sat Feb 23 19:47:04 2008
@@ -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': [...]
+}