def test_autoattribute_typed_variable(app):
actual = do_autodoc(app, 'attribute', 'target.typed_vars.Class.attr2')
assert list(actual) == [
'',
'.. py:attribute:: Class.attr2',
' :module: target.typed_vars',
' :type: int',
'',
]
def test_autoclass_content_init(app):
app.config.autoclass_content = 'init'
options = {"members": None}
actual = do_autodoc(app, 'module', 'target.autoclass_content', options)
assert list(actual) == [
'',
'.. py:module:: target.autoclass_content',
'',
'',
'.. py:class:: A()',
' :module: target.autoclass_content',
'',
' A class having no __init__, no __new__',
'',
'',
'.. py:class:: B()',
' :module: target.autoclass_content',
'',
' A class having __init__(no docstring), no __new__',
'',
'',
'.. py:class:: C()',
' :module: target.autoclass_content',
'',
' __init__ docstring',
'',
'',
'.. py:class:: D()',
' :module: target.autoclass_content',
'',
' A class having no __init__, __new__(no docstring)',
'',
'',
'.. py:class:: E()',
' :module: target.autoclass_content',
'',
' __new__ docstring',
'',
'',
'.. py:class:: F()',
' :module: target.autoclass_content',
'',
' __init__ docstring',
'',
'',
'.. py:class:: G()',
' :module: target.autoclass_content',
'',
' __init__ docstring',
'',
'',
'.. py:class:: H()',
' :module: target.autoclass_content',
'',
' __new__ docstring',
'',
]
def test_autoclass_content_class(app):
app.config.autoclass_content = 'class'
options = {"members": None}
actual = do_autodoc(app, 'module', 'target.autoclass_content', options)
assert list(actual) == [
'',
'.. py:module:: target.autoclass_content',
'',
'',
'.. py:class:: A',
' :module: target.autoclass_content',
'',
' A class having no __init__, no __new__',
'',
'',
'.. py:class:: B()',
' :module: target.autoclass_content',
'',
' A class having __init__(no docstring), no __new__',
'',
'',
'.. py:class:: C()',
' :module: target.autoclass_content',
'',
' A class having __init__, no __new__',
'',
'',
'.. py:class:: D',
' :module: target.autoclass_content',
'',
' A class having no __init__, __new__(no docstring)',
'',
'',
'.. py:class:: E',
' :module: target.autoclass_content',
'',
' A class having no __init__, __new__',
'',
'',
'.. py:class:: F()',
' :module: target.autoclass_content',
'',
' A class having both __init__ and __new__',
'',
'',
'.. py:class:: G()',
' :module: target.autoclass_content',
'',
' A class inherits __init__ without docstring.',
'',
'',
'.. py:class:: H()',
' :module: target.autoclass_content',
'',
' A class inherits __new__ without docstring.',
'',
]
def test_autodoc_type_aliases(app):
# default
options = {"members": None}
actual = do_autodoc(app, 'module', 'target.annotations', options)
assert list(actual) == [
'',
'.. py:module:: target.annotations',
'',
'',
'.. py:function:: mult(x: int, y: int) -> int',
' mult(x: float, y: float) -> float',
' :module: target.annotations',
'',
' docstring',
'',
'',
'.. py:function:: sum(x: int, y: int) -> int',
' :module: target.annotations',
'',
' docstring',
'',
]
# define aliases
app.config.autodoc_type_aliases = {'myint': 'myint'}
actual = do_autodoc(app, 'module', 'target.annotations', options)
assert list(actual) == [
'',
'.. py:module:: target.annotations',
'',
'',
'.. py:function:: mult(x: myint, y: myint) -> myint',
' mult(x: float, y: float) -> float',
' :module: target.annotations',
'',
' docstring',
'',
'',
'.. py:function:: sum(x: myint, y: myint) -> myint',
' :module: target.annotations',
'',
' docstring',
'',
]
def test_wrapped_function_contextmanager(app):
actual = do_autodoc(app, 'function', 'target.wrappedfunction.feeling_good')
assert list(actual) == [
'',
'.. py:function:: feeling_good(x: int, y: int) -> Generator',
' :module: target.wrappedfunction',
'',
" You'll feel better in this context!",
'',
]
def test_wrapped_function(app):
actual = do_autodoc(app, 'function', 'target.wrappedfunction.slow_function')
assert list(actual) == [
'',
'.. py:function:: slow_function(message, timeout)',
' :module: target.wrappedfunction',
'',
' This function is slow.',
'',
]
def test_callable(app):
actual = do_autodoc(app, 'function', 'target.callable.function')
assert list(actual) == [
'',
'.. py:function:: function(arg1, arg2, **kwargs)',
' :module: target.callable',
'',
' A callable object that behaves like a function.',
'',
]
def test_method(app):
actual = do_autodoc(app, 'function', 'target.callable.method')
assert list(actual) == [
'',
'.. py:function:: method(arg1, arg2)',
' :module: target.callable',
'',
' docstring of Callable.method().',
'',
]
def test_builtin_function(app):
actual = do_autodoc(app, 'function', 'os.umask')
assert list(actual) == [
'',
'.. py:function:: umask(mask, /)',
' :module: os',
'',
' Set the current numeric umask and return the previous umask.',
'',
]
def test_methoddescriptor(app):
actual = do_autodoc(app, 'function', 'builtins.int.__add__')
assert list(actual) == [
'',
'.. py:function:: __add__(self, value, /)',
' :module: builtins.int',
'',
' Return self+value.',
'',
]
def test_autodata_typed_variable(app):
actual = do_autodoc(app, 'data', 'target.typed_vars.attr2')
assert list(actual) == [
'',
'.. py:data:: attr2',
' :module: target.typed_vars',
' :type: str',
'',
' attr2',
'',
]
def test_autodata_novalue(app):
options = {'no-value': True}
actual = do_autodoc(app, 'data', 'target.integer', options)
assert list(actual) == [
'',
'.. py:data:: integer',
' :module: target',
'',
' documentation for the integer',
'',
]
def test_autodata(app):
actual = do_autodoc(app, 'data', 'target.integer')
assert list(actual) == [
'',
'.. py:data:: integer',
' :module: target',
' :value: 1',
'',
' documentation for the integer',
'',
]
def test_autoattribute(app):
actual = do_autodoc(app, 'attribute', 'target.Class.attr')
assert list(actual) == [
'',
'.. py:attribute:: Class.attr',
' :module: target',
" :value: 'bar'",
'',
' should be documented -- süß',
'',
]
def test_autoattribute_novalue(app):
options = {'no-value': True}
actual = do_autodoc(app, 'attribute', 'target.Class.attr', options)
assert list(actual) == [
'',
'.. py:attribute:: Class.attr',
' :module: target',
'',
' should be documented -- süß',
'',
]
def test_autodoc_inherit_docstrings(app):
assert app.config.autodoc_inherit_docstrings is True # default
actual = do_autodoc(app, 'method',
'target.inheritance.Derived.inheritedmeth')
assert list(actual) == [
'',
'.. py:method:: Derived.inheritedmeth()',
' :module: target.inheritance',
'',
' Inherited function.',
'',
]
# disable autodoc_inherit_docstrings
app.config.autodoc_inherit_docstrings = False
actual = do_autodoc(app, 'method',
'target.inheritance.Derived.inheritedmeth')
assert list(actual) == [
'', '.. py:method:: Derived.inheritedmeth()',
' :module: target.inheritance', ''
]
def test_process_docstring(app):
def on_process_docstring(app, what, name, obj, options, lines):
lines.clear()
lines.append('my docstring')
app.connect('autodoc-process-docstring', on_process_docstring)
actual = do_autodoc(app, 'function', 'target.process_docstring.func')
assert list(actual) == [
'', '.. py:function:: func()', ' :module: target.process_docstring',
'', ' my docstring'
]
def test_between(app):
app.connect('autodoc-process-docstring', between('---', ['function']))
actual = do_autodoc(app, 'function', 'target.process_docstring.func')
assert list(actual) == [
'',
'.. py:function:: func()',
' :module: target.process_docstring',
'',
' second line',
'',
]
def test_autodata_type_comment(app):
actual = do_autodoc(app, 'data', 'target.typed_vars.attr3')
assert list(actual) == [
'',
'.. py:data:: attr3',
' :module: target.typed_vars',
' :type: str',
" :value: ''",
'',
' attr3',
'',
]
def test_cfunction(app):
actual = do_autodoc(app, 'function', 'time.asctime')
assert list(actual) == [
'',
'.. py:function:: asctime([tuple]) -> string',
' :module: time',
'',
" Convert a time tuple to a string, e.g. 'Sat Jun 06 16:26:11 1998'.",
' When the time tuple is not present, current time as returned by localtime()',
' is used.',
'',
]
def test_singledispatch(app):
options = {}
actual = do_autodoc(app, 'function', 'target.singledispatch.func', options)
assert list(actual) == [
'',
'.. py:function:: func(arg, kwarg=None)',
' func(arg: int, kwarg=None)',
' func(arg: str, kwarg=None)',
' :module: target.singledispatch',
'',
' A function for general use.',
'',
]
def test_show_inheritance_for_subclass_of_generic_type(app):
options = {'show-inheritance': True}
actual = do_autodoc(app, 'class', 'target.classes.Quux', options)
assert list(actual) == [
'',
'.. py:class:: Quux(iterable=(), /)',
' :module: target.classes',
'',
' Bases: :class:`List`\\ [:obj:`Union`\\ [:class:`int`, :class:`float`]]',
'',
' A subclass of List[Union[int, float]]',
'',
]
def test_autoclass_content_and_docstring_signature_class(app):
app.config.autoclass_content = 'class'
options = {"members": None, "undoc-members": None}
actual = do_autodoc(app, 'module', 'target.docstring_signature', options)
assert list(actual) == [
'', '.. py:module:: target.docstring_signature', '', '',
'.. py:class:: A(foo, bar)', ' :module: target.docstring_signature',
'', '', '.. py:class:: B(foo, bar)',
' :module: target.docstring_signature', '', '',
'.. py:class:: C(foo, bar)', ' :module: target.docstring_signature',
'', '', '.. py:class:: D()', ' :module: target.docstring_signature',
''
]
def test_autodoc_typehints_signature(app):
options = {"members": None, "undoc-members": True}
actual = do_autodoc(app, 'module', 'target.typehints', options)
assert list(actual) == [
'',
'.. py:module:: target.typehints',
'',
'',
'.. py:class:: Math(s: str, o: object = None)',
' :module: target.typehints',
'',
'',
' .. py:method:: Math.decr(a: int, b: int = 1) -> int',
' :module: target.typehints',
'',
'',
' .. py:method:: Math.horse(a: str, b: int) -> None',
' :module: target.typehints',
'',
'',
' .. py:method:: Math.incr(a: int, b: int = 1) -> int',
' :module: target.typehints',
'',
'',
' .. py:method:: Math.nothing() -> None',
' :module: target.typehints',
'',
'',
'.. py:function:: complex_func(arg1: str, arg2: List[int], arg3: Tuple[int, '
'Union[str, Unknown]] = None, *args: str, **kwargs: str) -> None',
' :module: target.typehints',
'',
'',
'.. py:function:: decr(a: int, b: int = 1) -> int',
' :module: target.typehints',
'',
'',
'.. py:function:: incr(a: int, b: int = 1) -> int',
' :module: target.typehints',
'',
'',
'.. py:function:: missing_attr(c, a: str, b: Optional[str] = None) -> str',
' :module: target.typehints',
'',
'',
'.. py:function:: tuple_args(x: Tuple[int, Union[int, str]]) -> Tuple[int, int]',
' :module: target.typehints',
'',
]
def test_classes(app):
actual = do_autodoc(app, 'function', 'target.classes.Foo')
assert list(actual) == [
'',
'.. py:function:: Foo()',
' :module: target.classes',
'',
]
actual = do_autodoc(app, 'function', 'target.classes.Bar')
assert list(actual) == [
'',
'.. py:function:: Bar(x, y)',
' :module: target.classes',
'',
]
actual = do_autodoc(app, 'function', 'target.classes.Baz')
assert list(actual) == [
'',
'.. py:function:: Baz(x, y)',
' :module: target.classes',
'',
]
def test_decorators(app):
actual = do_autodoc(app, 'class', 'target.decorator.Baz')
assert list(actual) == [
'',
'.. py:class:: Baz(name=None, age=None)',
' :module: target.decorator',
'',
]
actual = do_autodoc(app, 'class', 'target.decorator.Qux')
assert list(actual) == [
'',
'.. py:class:: Qux(name=None, age=None)',
' :module: target.decorator',
'',
]
actual = do_autodoc(app, 'class', 'target.decorator.Quux')
assert list(actual) == [
'',
'.. py:class:: Quux(name=None, age=None)',
' :module: target.decorator',
'',
]
def test_autodoc_typehints_none(app):
options = {"members": None, "undoc-members": True}
actual = do_autodoc(app, 'module', 'target.typehints', options)
assert list(actual) == [
'',
'.. py:module:: target.typehints',
'',
'',
'.. py:class:: Math(s, o=None)',
' :module: target.typehints',
'',
'',
' .. py:method:: Math.decr(a, b=1)',
' :module: target.typehints',
'',
'',
' .. py:method:: Math.horse(a, b)',
' :module: target.typehints',
'',
'',
' .. py:method:: Math.incr(a, b=1)',
' :module: target.typehints',
'',
'',
' .. py:method:: Math.nothing()',
' :module: target.typehints',
'',
'',
'.. py:function:: complex_func(arg1, arg2, arg3=None, *args, **kwargs)',
' :module: target.typehints',
'',
'',
'.. py:function:: decr(a, b=1)',
' :module: target.typehints',
'',
'',
'.. py:function:: incr(a, b=1)',
' :module: target.typehints',
'',
'',
'.. py:function:: missing_attr(c, a, b=None)',
' :module: target.typehints',
'',
'',
'.. py:function:: tuple_args(x)',
' :module: target.typehints',
'',
]
def test_private_members(app):
app.config.autoclass_content = 'class'
options = {"members": None, "private-members": "_public_function"}
actual = do_autodoc(app, 'module', 'target.private', options)
assert list(actual) == [
'',
'.. py:module:: target.private',
'',
'',
'.. py:function:: _public_function(name)',
' :module: target.private',
'',
' public_function is a docstring().',
'',
' :meta public:',
'',
]
def test_autoclass_content_and_docstring_signature_init(app):
app.config.autoclass_content = 'init'
options = {"members": None, "undoc-members": None}
actual = do_autodoc(app, 'module', 'target.docstring_signature', options)
assert list(actual) == [
'', '.. py:module:: target.docstring_signature', '', '',
'.. py:class:: A(foo, bar)', ' :module: target.docstring_signature',
'', '', '.. py:class:: B(foo, bar, baz)',
' :module: target.docstring_signature', '', '',
'.. py:class:: C(foo, bar, baz)',
' :module: target.docstring_signature', '', '',
'.. py:class:: D(foo, bar, baz)',
' :module: target.docstring_signature', '', '',
'.. py:class:: E(foo: int, bar: int, baz: int) -> None',
' E(foo: str, bar: str, baz: str) -> None',
' :module: target.docstring_signature', ''
]
def test_autodoc_typehints_none_for_overload(app):
options = {"members": None}
actual = do_autodoc(app, 'module', 'target.overload', options)
assert list(actual) == [
'',
'.. py:module:: target.overload',
'',
'',
'.. py:class:: Bar(x, y)',
' :module: target.overload',
'',
' docstring',
'',
'',
'.. py:class:: Baz(x, y)',
' :module: target.overload',
'',
' docstring',
'',
'',
'.. py:class:: Foo(x, y)',
' :module: target.overload',
'',
' docstring',
'',
'',
'.. py:class:: Math()',
' :module: target.overload',
'',
' docstring',
'',
'',
' .. py:method:: Math.sum(x, y)',
' :module: target.overload',
'',
' docstring',
'',
'',
'.. py:function:: sum(x, y)',
' :module: target.overload',
'',
' docstring',
'',
]