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', '', ]