mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Update the test_autodoc for the autodoc refactorings and fix a few remaining bugs.
This commit is contained in:
Georg Brandl
@@ -3,7 +3,7 @@
|
||||
test_autodoc
|
||||
~~~~~~~~~~~~
|
||||
|
||||
Test the autodoc extension. This tests mainly the RstGenerator; the auto
|
||||
Test the autodoc extension. This tests mainly the Documenters; the auto
|
||||
directives are tested in a test source file translated by test_build.
|
||||
|
||||
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
|
||||
@@ -14,11 +14,13 @@ from util import *
|
||||
|
||||
from docutils.statemachine import ViewList
|
||||
|
||||
from sphinx.ext.autodoc import RstGenerator, cut_lines, between
|
||||
from sphinx.ext.autodoc import AutoDirective, Documenter, ModuleDocumenter, \
|
||||
ClassDocumenter, FunctionDocumenter, DataDocumenter, MethodDocumenter, \
|
||||
AttributeDocumenter, cut_lines, between, ALL
|
||||
|
||||
|
||||
def setup_module():
|
||||
global app, lid, options, gen
|
||||
global app, lid, options, directive
|
||||
|
||||
app = TestApp()
|
||||
app.builder.env.app = app
|
||||
@@ -34,27 +36,25 @@ def setup_module():
|
||||
synopsis = '',
|
||||
platform = '',
|
||||
deprecated = False,
|
||||
members = [],
|
||||
)
|
||||
|
||||
gen = TestGenerator(options, app)
|
||||
directive = Struct(
|
||||
env = app.builder.env,
|
||||
genopt = options,
|
||||
result = ViewList(),
|
||||
warn = warnfunc,
|
||||
filename_set = set(),
|
||||
)
|
||||
|
||||
def teardown_module():
|
||||
app.cleanup()
|
||||
|
||||
|
||||
class TestGenerator(RstGenerator):
|
||||
"""Generator that handles warnings without a reporter."""
|
||||
_warnings = []
|
||||
|
||||
def __init__(self, options, app):
|
||||
self.options = options
|
||||
self.env = app.builder.env
|
||||
self.lineno = 42
|
||||
self.filename_set = set()
|
||||
self.warnings = []
|
||||
self.result = ViewList()
|
||||
|
||||
def warn(self, msg):
|
||||
self.warnings.append(msg)
|
||||
def warnfunc(msg):
|
||||
_warnings.append(msg)
|
||||
|
||||
|
||||
processed_docstrings = []
|
||||
@@ -79,63 +79,66 @@ def skip_member(app, what, name, obj, skip, options):
|
||||
return True
|
||||
|
||||
|
||||
def test_resolve_name():
|
||||
# for modules
|
||||
assert gen.resolve_name('module', 'test_autodoc') == \
|
||||
('test_autodoc', [], None, None)
|
||||
assert gen.resolve_name('module', 'test.test_autodoc') == \
|
||||
('test.test_autodoc', [], None, None)
|
||||
def test_parse_name():
|
||||
def verify(objtype, name, result):
|
||||
inst = AutoDirective._registry[objtype](directive, name)
|
||||
assert inst.parse_name()
|
||||
assert (inst.modname, inst.objpath, inst.args, inst.retann) == result
|
||||
|
||||
assert gen.resolve_name('module', 'test(arg)') == \
|
||||
('test', [], None, None)
|
||||
assert 'ignoring signature arguments' in gen.warnings[0]
|
||||
del gen.warnings[:]
|
||||
# for modules
|
||||
verify('module', 'test_autodoc', ('test_autodoc', [], None, None))
|
||||
verify('module', 'test.test_autodoc', ('test.test_autodoc', [], None, None))
|
||||
verify('module', 'test(arg)', ('test', [], 'arg', None))
|
||||
assert 'signature arguments' in _warnings[0]
|
||||
del _warnings[:]
|
||||
|
||||
# for functions/classes
|
||||
assert gen.resolve_name('function', 'util.raises') == \
|
||||
('util', ['raises'], None, None)
|
||||
assert gen.resolve_name('function', 'util.raises(exc) -> None') == \
|
||||
('util', ['raises'], 'exc', 'None')
|
||||
gen.env.autodoc_current_module = 'util'
|
||||
assert gen.resolve_name('function', 'raises') == \
|
||||
('util', ['raises'], None, None)
|
||||
gen.env.autodoc_current_module = None
|
||||
gen.env.currmodule = 'util'
|
||||
assert gen.resolve_name('function', 'raises') == \
|
||||
('util', ['raises'], None, None)
|
||||
assert gen.resolve_name('class', 'TestApp') == \
|
||||
('util', ['TestApp'], None, None)
|
||||
verify('function', 'util.raises', ('util', ['raises'], None, None))
|
||||
verify('function', 'util.raises(exc) -> None',
|
||||
('util', ['raises'], 'exc', 'None'))
|
||||
directive.env.autodoc_current_module = 'util'
|
||||
verify('function', 'raises', ('util', ['raises'], None, None))
|
||||
directive.env.autodoc_current_module = None
|
||||
directive.env.currmodule = 'util'
|
||||
verify('function', 'raises', ('util', ['raises'], None, None))
|
||||
verify('class', 'TestApp', ('util', ['TestApp'], None, None))
|
||||
|
||||
# for members
|
||||
gen.env.currmodule = 'foo'
|
||||
assert gen.resolve_name('method', 'util.TestApp.cleanup') == \
|
||||
('util', ['TestApp', 'cleanup'], None, None)
|
||||
gen.env.currmodule = 'util'
|
||||
gen.env.currclass = 'Foo'
|
||||
gen.env.autodoc_current_class = 'TestApp'
|
||||
assert gen.resolve_name('method', 'cleanup') == \
|
||||
('util', ['TestApp', 'cleanup'], None, None)
|
||||
assert gen.resolve_name('method', 'TestApp.cleanup') == \
|
||||
('util', ['TestApp', 'cleanup'], None, None)
|
||||
directive.env.currmodule = 'foo'
|
||||
verify('method', 'util.TestApp.cleanup',
|
||||
('util', ['TestApp', 'cleanup'], None, None))
|
||||
directive.env.currmodule = 'util'
|
||||
directive.env.currclass = 'Foo'
|
||||
directive.env.autodoc_current_class = 'TestApp'
|
||||
verify('method', 'cleanup', ('util', ['TestApp', 'cleanup'], None, None))
|
||||
verify('method', 'TestApp.cleanup',
|
||||
('util', ['TestApp', 'cleanup'], None, None))
|
||||
|
||||
# and clean up
|
||||
gen.env.currmodule = None
|
||||
gen.env.currclass = None
|
||||
gen.env.autodoc_current_class = None
|
||||
directive.env.currmodule = None
|
||||
directive.env.currclass = None
|
||||
directive.env.autodoc_current_class = None
|
||||
|
||||
|
||||
def test_format_signature():
|
||||
def formatsig(objtype, name, obj, args, retann):
|
||||
inst = AutoDirective._registry[objtype](directive, name)
|
||||
inst.fullname = name
|
||||
inst.doc_as_attr = False # for class objtype
|
||||
inst.object = obj
|
||||
inst.args = args
|
||||
inst.retann = retann
|
||||
return inst.format_signature()
|
||||
|
||||
# no signatures for modules
|
||||
assert gen.format_signature('module', 'test', None, None, None) == ''
|
||||
assert formatsig('module', 'test', None, None, None) == ''
|
||||
|
||||
# test for functions
|
||||
def f(a, b, c=1, **d):
|
||||
pass
|
||||
assert gen.format_signature('function', 'f', f, None, None) == \
|
||||
'(a, b, c=1, **d)'
|
||||
assert gen.format_signature('function', 'f', f, 'a, b, c, d', None) == \
|
||||
'(a, b, c, d)'
|
||||
assert gen.format_signature('function', 'f', f, None, 'None') == \
|
||||
assert formatsig('function', 'f', f, None, None) == '(a, b, c=1, **d)'
|
||||
assert formatsig('function', 'f', f, 'a, b, c, d', None) == '(a, b, c, d)'
|
||||
assert formatsig('function', 'f', f, None, 'None') == \
|
||||
'(a, b, c=1, **d) -> None'
|
||||
|
||||
# test for classes
|
||||
@@ -145,16 +148,15 @@ def test_format_signature():
|
||||
pass
|
||||
# no signature for classes without __init__
|
||||
for C in (D, E):
|
||||
assert gen.format_signature('class', 'D', C, None, None) == ''
|
||||
assert formatsig('class', 'D', C, None, None) == ''
|
||||
class F:
|
||||
def __init__(self, a, b=None):
|
||||
pass
|
||||
class G(F, object):
|
||||
pass
|
||||
for C in (F, G):
|
||||
assert gen.format_signature('class', 'C', C, None, None) == \
|
||||
'(a, b=None)'
|
||||
assert gen.format_signature('class', 'C', D, 'a, b', 'X') == '(a, b) -> X'
|
||||
assert formatsig('class', 'C', C, None, None) == '(a, b=None)'
|
||||
assert formatsig('class', 'C', D, 'a, b', 'X') == '(a, b) -> X'
|
||||
|
||||
# test for methods
|
||||
class H:
|
||||
@@ -162,24 +164,22 @@ def test_format_signature():
|
||||
pass
|
||||
def foo2(b, *c):
|
||||
pass
|
||||
assert gen.format_signature('method', 'H.foo', H.foo1, None, None) == \
|
||||
'(b, *c)'
|
||||
assert gen.format_signature('method', 'H.foo', H.foo1, 'a', None) == \
|
||||
'(a)'
|
||||
assert gen.format_signature('method', 'H.foo', H.foo2, None, None) == \
|
||||
'(b, *c)'
|
||||
assert formatsig('method', 'H.foo', H.foo1, None, None) == '(b, *c)'
|
||||
assert formatsig('method', 'H.foo', H.foo1, 'a', None) == '(a)'
|
||||
assert formatsig('method', 'H.foo', H.foo2, None, None) == '(b, *c)'
|
||||
|
||||
# test exception handling
|
||||
raises(RuntimeError, gen.format_signature,
|
||||
'function', 'int', int, None, None)
|
||||
raises(TypeError, formatsig, 'function', 'int', int, None, None)
|
||||
|
||||
# test processing by event handler
|
||||
assert gen.format_signature('method', 'bar', H.foo1, None, None) == '42'
|
||||
assert formatsig('method', 'bar', H.foo1, None, None) == '42'
|
||||
|
||||
|
||||
def test_get_doc():
|
||||
def getdocl(*args):
|
||||
ds = gen.get_doc(*args)
|
||||
def getdocl(objtype, obj, encoding=None):
|
||||
inst = AutoDirective._registry[objtype](directive, 'tmp')
|
||||
inst.object = obj
|
||||
ds = inst.get_doc(encoding)
|
||||
# for testing purposes, concat them and strip the empty line at the end
|
||||
return sum(ds, [])[:-1]
|
||||
|
||||
@@ -222,11 +222,11 @@ def test_get_doc():
|
||||
"""Class docstring"""
|
||||
def __init__(self):
|
||||
"""Init docstring"""
|
||||
gen.env.config.autoclass_content = 'class'
|
||||
directive.env.config.autoclass_content = 'class'
|
||||
assert getdocl('class', C) == ['Class docstring']
|
||||
gen.env.config.autoclass_content = 'init'
|
||||
directive.env.config.autoclass_content = 'init'
|
||||
assert getdocl('class', C) == ['Init docstring']
|
||||
gen.env.config.autoclass_content = 'both'
|
||||
directive.env.config.autoclass_content = 'both'
|
||||
assert getdocl('class', C) == ['Class docstring', '', 'Init docstring']
|
||||
|
||||
class D:
|
||||
@@ -244,8 +244,11 @@ def test_get_doc():
|
||||
|
||||
|
||||
def test_docstring_processing():
|
||||
def process(what, name, obj):
|
||||
return list(gen.process_doc(gen.get_doc(what, obj), what, name, obj))
|
||||
def process(objtype, name, obj):
|
||||
inst = AutoDirective._registry[objtype](directive, name)
|
||||
inst.object = obj
|
||||
inst.fullname = name
|
||||
return list(inst.process_doc(inst.get_doc()))
|
||||
|
||||
class E:
|
||||
def __init__(self):
|
||||
@@ -279,122 +282,123 @@ def test_docstring_processing():
|
||||
|
||||
|
||||
def test_generate():
|
||||
def assert_warns(warn_str, *args):
|
||||
gen.generate(*args)
|
||||
assert len(gen.result) == 0, gen.result
|
||||
assert len(gen.warnings) == 1, gen.warnings
|
||||
assert warn_str in gen.warnings[0], gen.warnings
|
||||
del gen.warnings[:]
|
||||
def assert_warns(warn_str, objtype, name, **kw):
|
||||
inst = AutoDirective._registry[objtype](directive, name)
|
||||
inst.generate(**kw)
|
||||
assert len(directive.result) == 0, directive.result
|
||||
assert len(_warnings) == 1, _warnings
|
||||
assert warn_str in _warnings[0], _warnings
|
||||
del _warnings[:]
|
||||
|
||||
def assert_works(*args):
|
||||
gen.generate(*args)
|
||||
assert gen.result
|
||||
assert len(gen.warnings) == 0, gen.warnings
|
||||
del gen.result[:]
|
||||
def assert_works(objtype, name, **kw):
|
||||
inst = AutoDirective._registry[objtype](directive, name)
|
||||
inst.generate(**kw)
|
||||
assert directive.result
|
||||
assert len(_warnings) == 0, _warnings
|
||||
del directive.result[:]
|
||||
|
||||
def assert_processes(items, *args):
|
||||
def assert_processes(items, objtype, name, **kw):
|
||||
del processed_docstrings[:]
|
||||
del processed_signatures[:]
|
||||
assert_works(*args)
|
||||
assert_works(objtype, name, **kw)
|
||||
assert set(processed_docstrings) | set(processed_signatures) == \
|
||||
set(items)
|
||||
|
||||
def assert_result_contains(item, *args):
|
||||
gen.generate(*args)
|
||||
#print '\n'.join(gen.result)
|
||||
assert len(gen.warnings) == 0, gen.warnings
|
||||
assert item in gen.result
|
||||
del gen.result[:]
|
||||
def assert_result_contains(item, objtype, name, **kw):
|
||||
inst = AutoDirective._registry[objtype](directive, name)
|
||||
inst.generate(**kw)
|
||||
#print '\n'.join(directive.result)
|
||||
assert len(_warnings) == 0, _warnings
|
||||
assert item in directive.result
|
||||
del directive.result[:]
|
||||
|
||||
# no module found?
|
||||
assert_warns("import for autodocumenting 'foobar'",
|
||||
'function', 'foobar', None, None)
|
||||
'function', 'foobar', more_content=None)
|
||||
# importing
|
||||
assert_warns("import/find module 'test_foobar'",
|
||||
'module', 'test_foobar', None, None)
|
||||
'module', 'test_foobar', more_content=None)
|
||||
# attributes missing
|
||||
assert_warns("import/find function 'util.foobar'",
|
||||
'function', 'util.foobar', None, None)
|
||||
'function', 'util.foobar', more_content=None)
|
||||
|
||||
# test auto and given content mixing
|
||||
gen.env.currmodule = 'test_autodoc'
|
||||
assert_result_contains(' Function.', 'method', 'Class.meth', [], None)
|
||||
directive.env.currmodule = 'test_autodoc'
|
||||
assert_result_contains(' Function.', 'method', 'Class.meth')
|
||||
add_content = ViewList()
|
||||
add_content.append('Content.', '', 0)
|
||||
assert_result_contains(' Function.', 'method',
|
||||
'Class.meth', [], add_content)
|
||||
'Class.meth', more_content=add_content)
|
||||
assert_result_contains(' Content.', 'method',
|
||||
'Class.meth', [], add_content)
|
||||
'Class.meth', more_content=add_content)
|
||||
|
||||
# test check_module
|
||||
gen.generate('function', 'raises', None, None, check_module=True)
|
||||
assert len(gen.result) == 0
|
||||
inst = FunctionDocumenter(directive, 'raises')
|
||||
inst.generate(check_module=True)
|
||||
assert len(directive.result) == 0
|
||||
|
||||
# assert that exceptions can be documented
|
||||
assert_works('exception', 'test_autodoc.CustomEx', ['__all__'], None)
|
||||
assert_works('exception', 'test_autodoc.CustomEx', [], None)
|
||||
assert_works('exception', 'test_autodoc.CustomEx', all_members=True)
|
||||
assert_works('exception', 'test_autodoc.CustomEx')
|
||||
|
||||
# test diverse inclusion settings for members
|
||||
should = [('class', 'test_autodoc.Class')]
|
||||
assert_processes(should, 'class', 'Class', [], None)
|
||||
assert_processes(should, 'class', 'Class')
|
||||
should.extend([('method', 'test_autodoc.Class.meth')])
|
||||
assert_processes(should, 'class', 'Class', ['meth'], None)
|
||||
options.members = ['meth']
|
||||
assert_processes(should, 'class', 'Class')
|
||||
should.extend([('attribute', 'test_autodoc.Class.prop'),
|
||||
('attribute', 'test_autodoc.Class.attr'),
|
||||
('attribute', 'test_autodoc.Class.docattr'),
|
||||
('attribute', 'test_autodoc.Class.udocattr')])
|
||||
assert_processes(should, 'class', 'Class', ['__all__'], None)
|
||||
options.members = ALL
|
||||
assert_processes(should, 'class', 'Class')
|
||||
options.undoc_members = True
|
||||
should.append(('method', 'test_autodoc.Class.undocmeth'))
|
||||
assert_processes(should, 'class', 'Class', ['__all__'], None)
|
||||
assert_processes(should, 'class', 'Class')
|
||||
options.inherited_members = True
|
||||
should.append(('method', 'test_autodoc.Class.inheritedmeth'))
|
||||
assert_processes(should, 'class', 'Class', ['__all__'], None)
|
||||
assert_processes(should, 'class', 'Class')
|
||||
|
||||
options.members = []
|
||||
# test module flags
|
||||
assert_result_contains('.. module:: test_autodoc',
|
||||
'module', 'test_autodoc', [], None)
|
||||
assert_result_contains('.. module:: test_autodoc', 'module', 'test_autodoc')
|
||||
options.synopsis = 'Synopsis'
|
||||
assert_result_contains(' :synopsis: Synopsis',
|
||||
'module', 'test_autodoc', [], None)
|
||||
assert_result_contains(' :synopsis: Synopsis', 'module', 'test_autodoc')
|
||||
options.deprecated = True
|
||||
assert_result_contains(' :deprecated:',
|
||||
'module', 'test_autodoc', [], None)
|
||||
assert_result_contains(' :deprecated:', 'module', 'test_autodoc')
|
||||
options.platform = 'Platform'
|
||||
assert_result_contains(' :platform: Platform',
|
||||
'module', 'test_autodoc', [], None)
|
||||
assert_result_contains(' :platform: Platform', 'module', 'test_autodoc')
|
||||
# test if __all__ is respected for modules
|
||||
assert_result_contains('.. class:: Class',
|
||||
'module', 'test_autodoc', ['__all__'], None)
|
||||
options.members = ALL
|
||||
assert_result_contains('.. class:: Class', 'module', 'test_autodoc')
|
||||
try:
|
||||
assert_result_contains('.. exception:: CustomEx',
|
||||
'module', 'test_autodoc', ['__all__'], None)
|
||||
assert_result_contains('.. exception:: CustomEx', 'module', 'test_autodoc')
|
||||
except AssertionError:
|
||||
pass
|
||||
else:
|
||||
assert False, 'documented CustomEx which is not in __all__'
|
||||
|
||||
# test noindex flag
|
||||
options.members = []
|
||||
options.noindex = True
|
||||
assert_result_contains(' :noindex:', 'module', 'test_autodoc', [], None)
|
||||
assert_result_contains(' :noindex:', 'class', 'Base', [], None)
|
||||
assert_result_contains(' :noindex:', 'module', 'test_autodoc')
|
||||
assert_result_contains(' :noindex:', 'class', 'Base')
|
||||
|
||||
# okay, now let's get serious about mixing Python and C signature stuff
|
||||
assert_result_contains('.. class:: CustomDict', 'class', 'CustomDict',
|
||||
['__all__'], None)
|
||||
all_members=True)
|
||||
|
||||
# test inner class handling
|
||||
assert_processes([('class', 'test_autodoc.Outer'),
|
||||
('class', 'test_autodoc.Outer.Inner'),
|
||||
('method', 'test_autodoc.Outer.Inner.meth')],
|
||||
'class', 'Outer', ['__all__'], None)
|
||||
'class', 'Outer', all_members=True)
|
||||
|
||||
# test generation for C modules (which have no source file)
|
||||
gen.env.currmodule = 'time'
|
||||
assert_processes([('function', 'time.asctime')],
|
||||
'function', 'asctime', [], None)
|
||||
assert_processes([('function', 'time.asctime')],
|
||||
'function', 'asctime', [], None)
|
||||
directive.env.currmodule = 'time'
|
||||
assert_processes([('function', 'time.asctime')], 'function', 'asctime')
|
||||
assert_processes([('function', 'time.asctime')], 'function', 'asctime')
|
||||
|
||||
|
||||
# --- generate fodder ------------
|
||||
|
||||
Reference in New Issue
Block a user