IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Add an option for the coverage builder if source-undocumented items are matched.

Browse Source
This commit is contained in:
Georg Brandl 2011-01-04 22:50:13 +01:00
parent 7616639622
commit 208e8a66e2
3 changed files with 30 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
doc/ext/coverage.rst
View File

@ -14,6 +14,7 @@ This extension features one additional builder, the :class:`CoverageBuilder`.
.. todo:: Write this section.
Several new configuration values can be used to specify what the builder
should check:
@ -30,3 +31,14 @@ should check:
.. confval:: coverage_ignore_c_items
.. confval:: coverage_write_headline
Set to ``False`` to not write headlines.
.. versionadded:: 1.1
.. confval:: coverage_skip_undoc_in_source
Skip objects that are not documented in the source with a docstring.
``False`` by default.
.. versionadded:: 1.1

23
sphinx/ext/coverage.py
View File

@ -105,7 +105,8 @@ class CoverageBuilder(Builder):
output_file = path.join(self.outdir, 'c.txt')
op = open(output_file, 'w')
try:
write_header(op, 'Undocumented C API elements', '=')
if self.config.coverage_write_headline:
write_header(op, 'Undocumented C API elements', '=')
op.write('\n')
for filename, undoc in self.c_undoc.iteritems():
@ -120,6 +121,8 @@ class CoverageBuilder(Builder):
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:
@ -160,13 +163,17 @@ class CoverageBuilder(Builder):
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 and not obj.__doc__:
if full_name not in objects:
if skip_undoc and not obj.__doc__:
continue
# not documented at all
classes[name] = []
continue
@ -177,17 +184,18 @@ class CoverageBuilder(Builder):
if attr_name not in obj.__dict__:
continue
attr = getattr(obj, attr_name)
if (not inspect.ismethod(attr)
and not inspect.isfunction(attr)):
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:
if len(obj.__doc__) > 0:
continue
attrs.append(attr_name)
if attrs:
@ -252,4 +260,5 @@ def setup(app):
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', {}, False)
app.add_config_value('coverage_write_headline', True, False)
app.add_config_value('coverage_skip_undoc_in_source', False, False)

2
tests/test_coverage.py
View File

@ -27,6 +27,8 @@ def test_build(app):
assert ' * function\n' not in py_undoc # these two are documented
assert ' * Class\n' not in py_undoc # in autodoc.txt
assert ' * mod -- No module named mod' # in the "failed import" section
c_undoc = (app.outdir / 'c.txt').text()
assert c_undoc.startswith('Undocumented C API elements\n'
'===========================\n')