+++ /dev/null
-# -*- coding: utf-8 -*-
-"""
- sphinx.ext.coverage
- ~~~~~~~~~~~~~~~~~~~
-
- Check Python modules and C API for coverage. Mostly written by Josip
- Dzolonga for the Google Highly Open Participation contest.
-
- :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
- :license: BSD, see LICENSE for details.
-"""
-
-import re
-import glob
-import inspect
-import cPickle as pickle
-from os import path
-
-from sphinx.builders import Builder
-
-
-# utility
-def write_header(f, text, char='-'):
- f.write(text + '\n')
- f.write(char * len(text) + '\n')
-
-def compile_regex_list(name, exps, warnfunc):
- lst = []
- for exp in exps:
- try:
- lst.append(re.compile(exp))
- except Exception:
- warnfunc('invalid regex %r in %s' % (exp, name))
- return lst
-
-
-class CoverageBuilder(Builder):
-
- name = 'coverage'
-
- def init(self):
- self.c_sourcefiles = []
- for pattern in self.config.coverage_c_path:
- pattern = path.join(self.srcdir, pattern)
- self.c_sourcefiles.extend(glob.glob(pattern))
-
- self.c_regexes = []
- for (name, exp) in self.config.coverage_c_regexes.items():
- try:
- self.c_regexes.append((name, re.compile(exp)))
- except Exception:
- self.warn('invalid regex %r in coverage_c_regexes' % exp)
-
- self.c_ignorexps = {}
- for (name, exps) in self.config.coverage_ignore_c_items.iteritems():
- self.c_ignorexps[name] = compile_regex_list(
- 'coverage_ignore_c_items', exps, self.warn)
- self.mod_ignorexps = compile_regex_list(
- 'coverage_ignore_modules', self.config.coverage_ignore_modules,
- self.warn)
- self.cls_ignorexps = compile_regex_list(
- 'coverage_ignore_classes', self.config.coverage_ignore_classes,
- self.warn)
- self.fun_ignorexps = compile_regex_list(
- 'coverage_ignore_functions', self.config.coverage_ignore_functions,
- self.warn)
-
- def get_outdated_docs(self):
- return 'coverage overview'
-
- def write(self, *ignored):
- self.py_undoc = {}
- self.build_py_coverage()
- self.write_py_coverage()
-
- self.c_undoc = {}
- self.build_c_coverage()
- self.write_c_coverage()
-
- def build_c_coverage(self):
- # Fetch all the info from the header files
- c_objects = self.env.domaindata['c']['objects']
- for filename in self.c_sourcefiles:
- undoc = []
- f = open(filename, 'r')
- try:
- for line in f:
- for key, regex in self.c_regexes:
- match = regex.match(line)
- if match:
- name = match.groups()[0]
- if name not in c_objects:
- for exp in self.c_ignorexps.get(key, ()):
- if exp.match(name):
- break
- else:
- undoc.append((key, name))
- continue
- finally:
- f.close()
- if undoc:
- self.c_undoc[filename] = undoc
-
- def write_c_coverage(self):
- output_file = path.join(self.outdir, 'c.txt')
- op = open(output_file, 'w')
- try:
- if self.config.coverage_write_headline:
- write_header(op, 'Undocumented C API elements', '=')
- op.write('\n')
-
- for filename, undoc in self.c_undoc.iteritems():
- write_header(op, filename)
- for typ, name in undoc:
- op.write(' * %-50s [%9s]\n' % (name, typ))
- op.write('\n')
- finally:
- op.close()
-
- def build_py_coverage(self):
- objects = self.env.domaindata['py']['objects']
- modules = self.env.domaindata['py']['modules']
-
- skip_undoc = self.config.coverage_skip_undoc_in_source
-
- for mod_name in modules:
- ignore = False
- for exp in self.mod_ignorexps:
- if exp.match(mod_name):
- ignore = True
- break
- if ignore:
- continue
-
- try:
- mod = __import__(mod_name, fromlist=['foo'])
- except ImportError, err:
- self.warn('module %s could not be imported: %s' %
- (mod_name, err))
- self.py_undoc[mod_name] = {'error': err}
- continue
-
- funcs = []
- classes = {}
-
- for name, obj in inspect.getmembers(mod):
- # diverse module attributes are ignored:
- if name[0] == '_':
- # begins in an underscore
- continue
- if not hasattr(obj, '__module__'):
- # cannot be attributed to a module
- continue
- if obj.__module__ != mod_name:
- # is not defined in this module
- continue
-
- full_name = '%s.%s' % (mod_name, name)
-
- if inspect.isfunction(obj):
- if full_name not in objects:
- for exp in self.fun_ignorexps:
- if exp.match(name):
- break
- else:
- if skip_undoc and not obj.__doc__:
- continue
- funcs.append(name)
- elif inspect.isclass(obj):
- for exp in self.cls_ignorexps:
- if exp.match(name):
- break
- else:
- if full_name not in objects:
- if skip_undoc and not obj.__doc__:
- continue
- # not documented at all
- classes[name] = []
- continue
-
- attrs = []
-
- for attr_name in dir(obj):
- if attr_name not in obj.__dict__:
- continue
- attr = getattr(obj, attr_name)
- if not (inspect.ismethod(attr) or
- inspect.isfunction(attr)):
- continue
- if attr_name[0] == '_':
- # starts with an underscore, ignore it
- continue
- if skip_undoc and not attr.__doc__:
- # skip methods without docstring if wished
- continue
-
- full_attr_name = '%s.%s' % (full_name, attr_name)
- if full_attr_name not in objects:
- attrs.append(attr_name)
-
- if attrs:
- # some attributes are undocumented
- classes[name] = attrs
-
- self.py_undoc[mod_name] = {'funcs': funcs, 'classes': classes}
-
- def write_py_coverage(self):
- output_file = path.join(self.outdir, 'python.txt')
- op = open(output_file, 'w')
- failed = []
- try:
- if self.config.coverage_write_headline:
- write_header(op, 'Undocumented Python objects', '=')
- keys = self.py_undoc.keys()
- keys.sort()
- for name in keys:
- undoc = self.py_undoc[name]
- if 'error' in undoc:
- failed.append((name, undoc['error']))
- else:
- if not undoc['classes'] and not undoc['funcs']:
- continue
-
- write_header(op, name)
- if undoc['funcs']:
- op.write('Functions:\n')
- op.writelines(' * %s\n' % x for x in undoc['funcs'])
- op.write('\n')
- if undoc['classes']:
- op.write('Classes:\n')
- for name, methods in sorted(undoc['classes'].iteritems()):
- if not methods:
- op.write(' * %s\n' % name)
- else:
- op.write(' * %s -- missing methods:\n' % name)
- op.writelines(' - %s\n' % x for x in methods)
- op.write('\n')
-
- if failed:
- write_header(op, 'Modules that failed to import')
- op.writelines(' * %s -- %s\n' % x for x in failed)
- finally:
- op.close()
-
- def finish(self):
- # dump the coverage data to a pickle file too
- picklepath = path.join(self.outdir, 'undoc.pickle')
- dumpfile = open(picklepath, 'wb')
- try:
- pickle.dump((self.py_undoc, self.c_undoc), dumpfile)
- finally:
- dumpfile.close()
-
-
-def setup(app):
- app.add_builder(CoverageBuilder)
- app.add_config_value('coverage_ignore_modules', [], False)
- app.add_config_value('coverage_ignore_functions', [], False)
- app.add_config_value('coverage_ignore_classes', [], False)
- app.add_config_value('coverage_c_path', [], False)
- app.add_config_value('coverage_c_regexes', {}, False)
- app.add_config_value('coverage_ignore_c_items', {}, False)
- app.add_config_value('coverage_write_headline', True, False)
- app.add_config_value('coverage_skip_undoc_in_source', False, False)
projects / thirdparty / tornado.git / commitdiff
