| # -*- 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) |
