Adding upstream version 5.3.0.upstream/5.3.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

59 files changed, 1426 insertions, 0 deletions

diff --git a/tests/roots/test-ext-autodoc/autodoc_dummy_bar.py b/tests/roots/test-ext-autodoc/autodoc_dummy_bar.py
new file mode 100644
index 0000000..151818b
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/autodoc_dummy_bar.py
@@ -0,0 +1,6 @@
+from bug2437.autodoc_dummy_foo import Foo
+
+
+class Bar(object):
+    """Dummy class Bar with alias."""
+    my_name = Foo
diff --git a/tests/roots/test-ext-autodoc/autodoc_dummy_module.py b/tests/roots/test-ext-autodoc/autodoc_dummy_module.py
new file mode 100644
index 0000000..c05d96e
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/autodoc_dummy_module.py
@@ -0,0 +1,6 @@
+from dummy import *
+
+
+def test():
+    """Dummy function using dummy.*"""
+    dummy_function()
diff --git a/tests/roots/test-ext-autodoc/bug2437/__init__.py b/tests/roots/test-ext-autodoc/bug2437/__init__.py
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/bug2437/__init__.py
diff --git a/tests/roots/test-ext-autodoc/bug2437/autodoc_dummy_foo.py b/tests/roots/test-ext-autodoc/bug2437/autodoc_dummy_foo.py
new file mode 100644
index 0000000..b578a22
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/bug2437/autodoc_dummy_foo.py
@@ -0,0 +1,3 @@
+class Foo(object):
+    """Dummy class Foo."""
+    pass
diff --git a/tests/roots/test-ext-autodoc/conf.py b/tests/roots/test-ext-autodoc/conf.py
new file mode 100644
index 0000000..979a709
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/conf.py
@@ -0,0 +1,15 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('.'))
+
+extensions = ['sphinx.ext.autodoc']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+autodoc_mock_imports = [
+    'dummy'
+]
+
+nitpicky = True
diff --git a/tests/roots/test-ext-autodoc/index.rst b/tests/roots/test-ext-autodoc/index.rst
new file mode 100644
index 0000000..eb10829
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/index.rst
@@ -0,0 +1,15 @@
+
+.. automodule:: autodoc_dummy_module
+   :members:
+
+.. automodule:: bug2437.autodoc_dummy_foo
+   :members:
+
+.. automodule:: autodoc_dummy_bar
+   :members:
+
+.. autofunction:: target.typehints.incr
+
+.. autofunction:: target.overload.sum
+
+.. autofunction:: target.typehints.tuple_args
diff --git a/tests/roots/test-ext-autodoc/target/TYPE_CHECKING.py b/tests/roots/test-ext-autodoc/target/TYPE_CHECKING.py
new file mode 100644
index 0000000..aa7eb99
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/TYPE_CHECKING.py
@@ -0,0 +1,8 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from io import StringIO
+
+
+class Foo:
+    attr1: "StringIO"
diff --git a/tests/roots/test-ext-autodoc/target/__init__.py b/tests/roots/test-ext-autodoc/target/__init__.py
new file mode 100644
index 0000000..0d39c66
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/__init__.py
@@ -0,0 +1,204 @@
+import enum
+from io import StringIO
+
+from sphinx.util import save_traceback
+
+__all__ = ['Class']
+
+#: documentation for the integer
+integer = 1
+
+
+def raises(exc, func, *args, **kwds):
+    """Raise AssertionError if ``func(*args, **kwds)`` does not raise *exc*."""
+    pass
+
+
+class CustomEx(Exception):
+    """My custom exception."""
+
+    def f(self):
+        """Exception method."""
+
+
+def _funky_classmethod(name, b, c, d, docstring=None):
+    """Generates a classmethod for a class from a template by filling out
+    some arguments."""
+    def template(cls, a, b, c, d=4, e=5, f=6):
+        return a, b, c, d, e, f
+    from functools import partial
+    function = partial(template, b=b, c=c, d=d)
+    function.__name__ = name
+    function.__doc__ = docstring
+    return classmethod(function)
+
+
+class Class(object):
+    """Class to document."""
+
+    def meth(self):
+        """Function."""
+
+    def undocmeth(self):
+        pass
+
+    def skipmeth(self):
+        """Method that should be skipped."""
+
+    def excludemeth(self):
+        """Method that should be excluded."""
+
+    # should not be documented
+    skipattr = 'foo'
+
+    #: should be documented -- süß
+    attr = 'bar'
+
+    docattr = 'baz'
+    """should likewise be documented -- süß"""
+
+    udocattr = 'quux'
+    """should be documented as well - süß"""
+
+    # initialized to any class imported from another module
+    mdocattr = StringIO()
+    """should be documented as well - süß"""
+
+    roger = _funky_classmethod("roger", 2, 3, 4)
+
+    moore = _funky_classmethod("moore", 9, 8, 7,
+                               docstring="moore(a, e, f) -> happiness")
+
+    def __init__(self, arg):
+        self.inst_attr_inline = None  #: an inline documented instance attr
+        #: a documented instance attribute
+        self.inst_attr_comment = None
+        self.inst_attr_string = None
+        """a documented instance attribute"""
+        self._private_inst_attr = None  #: a private instance attribute
+
+    def __special1__(self):
+        """documented special method"""
+
+    def __special2__(self):
+        # undocumented special method
+        pass
+
+
+class CustomDict(dict):
+    """Docstring."""
+
+
+def function(foo, *args, **kwds):
+    """
+    Return spam.
+    """
+    pass
+
+
+class Outer(object):
+    """Foo"""
+
+    class Inner(object):
+        """Foo"""
+
+        def meth(self):
+            """Foo"""
+
+    # should be documented as an alias
+    factory = dict
+
+
+class InnerChild(Outer.Inner):
+    """InnerChild docstring"""
+
+
+class DocstringSig(object):
+    def __new__(cls, *new_args, **new_kwargs):
+        """__new__(cls, d, e=1) -> DocstringSig
+First line of docstring
+
+        rest of docstring
+        """
+
+    def __init__(self, *init_args, **init_kwargs):
+        """__init__(self, a, b=1) -> None
+First line of docstring
+
+        rest of docstring
+        """
+
+    def meth(self):
+        """meth(FOO, BAR=1) -> BAZ
+First line of docstring
+
+        rest of docstring
+        """
+
+    def meth2(self):
+        """First line, no signature
+        Second line followed by indentation::
+
+            indented line
+        """
+
+    @property
+    def prop1(self):
+        """DocstringSig.prop1(self)
+        First line of docstring
+        """
+        return 123
+
+    @property
+    def prop2(self):
+        """First line of docstring
+        Second line of docstring
+        """
+        return 456
+
+
+class StrRepr(str):
+    """docstring"""
+
+    def __repr__(self):
+        return self
+
+
+class AttCls(object):
+    a1 = StrRepr('hello\nworld')
+    a2 = None
+
+
+class InstAttCls(object):
+    """Class with documented class and instance attributes."""
+
+    #: Doc comment for class attribute InstAttCls.ca1.
+    #: It can have multiple lines.
+    ca1 = 'a'
+
+    ca2 = 'b'    #: Doc comment for InstAttCls.ca2. One line only.
+
+    ca3 = 'c'
+    """Docstring for class attribute InstAttCls.ca3."""
+
+    def __init__(self):
+        #: Doc comment for instance attribute InstAttCls.ia1
+        self.ia1 = 'd'
+
+        self.ia2 = 'e'
+        """Docstring for instance attribute InstAttCls.ia2."""
+
+
+class CustomIter(object):
+    def __init__(self):
+        """Create a new `CustomIter`."""
+        self.values = range(10)
+
+    def __iter__(self):
+        """Iterate squares of each value."""
+        for i in self.values:
+            yield i ** 2
+
+    def snafucate(self):
+        """Makes this snafucated."""
+        print("snafucated")
diff --git a/tests/roots/test-ext-autodoc/target/abstractmethods.py b/tests/roots/test-ext-autodoc/target/abstractmethods.py
new file mode 100644
index 0000000..a4396d5
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/abstractmethods.py
@@ -0,0 +1,29 @@
+from abc import abstractmethod
+
+
+class Base():
+    def meth(self):
+        pass
+
+    @abstractmethod
+    def abstractmeth(self):
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def staticmeth():
+        pass
+
+    @classmethod
+    @abstractmethod
+    def classmeth(cls):
+        pass
+
+    @property
+    @abstractmethod
+    def prop(self):
+        pass
+
+    @abstractmethod
+    async def coroutinemeth(self):
+        pass
diff --git a/tests/roots/test-ext-autodoc/target/annotated.py b/tests/roots/test-ext-autodoc/target/annotated.py
new file mode 100644
index 0000000..4271882
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/annotated.py
@@ -0,0 +1,6 @@
+from typing import Annotated
+
+
+def hello(name: Annotated[str, "attribute"]) -> None:
+    """docstring"""
+    pass
diff --git a/tests/roots/test-ext-autodoc/target/autoclass_content.py b/tests/roots/test-ext-autodoc/target/autoclass_content.py
new file mode 100644
index 0000000..52b9806
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/autoclass_content.py
@@ -0,0 +1,47 @@
+class A:
+    """A class having no __init__, no __new__"""
+
+
+class B:
+    """A class having __init__(no docstring), no __new__"""
+    def __init__(self):
+        pass
+
+
+class C:
+    """A class having __init__, no __new__"""
+    def __init__(self):
+        """__init__ docstring"""
+
+
+class D:
+    """A class having no __init__, __new__(no docstring)"""
+    def __new__(cls):
+        pass
+
+
+class E:
+    """A class having no __init__, __new__"""
+    def __new__(cls):
+        """__new__ docstring"""
+
+
+class F:
+    """A class having both __init__ and __new__"""
+    def __init__(self):
+        """__init__ docstring"""
+
+    def __new__(cls):
+        """__new__ docstring"""
+
+
+class G(C):
+    """A class inherits __init__ without docstring."""
+    def __init__(self):
+        pass
+
+
+class H(E):
+    """A class inherits __new__ without docstring."""
+    def __init__(self):
+        pass
diff --git a/tests/roots/test-ext-autodoc/target/autodoc_type_aliases.py b/tests/roots/test-ext-autodoc/target/autodoc_type_aliases.py
new file mode 100644
index 0000000..f2c07a0
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/autodoc_type_aliases.py
@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import io
+from typing import Optional, overload
+
+myint = int
+
+#: docstring
+variable: myint
+
+#: docstring
+variable2 = None  # type: myint
+
+#: docstring
+variable3: Optional[myint]
+
+
+def read(r: io.BytesIO) -> io.StringIO:
+    """docstring"""
+
+
+def sum(x: myint, y: myint) -> myint:
+    """docstring"""
+    return x + y
+
+
+@overload
+def mult(x: myint, y: myint) -> myint:
+    ...
+
+
+@overload
+def mult(x: float, y: float) -> float:
+    ...
+
+
+def mult(x, y):
+    """docstring"""
+    return x, y
+
+
+class Foo:
+    """docstring"""
+
+    #: docstring
+    attr1: myint
+
+    def __init__(self):
+        self.attr2: myint = None  #: docstring
diff --git a/tests/roots/test-ext-autodoc/target/bound_method.py b/tests/roots/test-ext-autodoc/target/bound_method.py
new file mode 100644
index 0000000..d48b9ee
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/bound_method.py
@@ -0,0 +1,7 @@
+class Cls:
+    def method(self):
+        """Method docstring"""
+        pass
+
+
+bound_method = Cls().method
diff --git a/tests/roots/test-ext-autodoc/target/cached_property.py b/tests/roots/test-ext-autodoc/target/cached_property.py
new file mode 100644
index 0000000..63ec09f
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/cached_property.py
@@ -0,0 +1,7 @@
+from functools import cached_property
+
+
+class Foo:
+    @cached_property
+    def prop(self) -> int:
+        return 1
diff --git a/tests/roots/test-ext-autodoc/target/callable.py b/tests/roots/test-ext-autodoc/target/callable.py
new file mode 100644
index 0000000..6fcd505
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/callable.py
@@ -0,0 +1,13 @@
+class Callable():
+    """A callable object that behaves like a function."""
+
+    def __call__(self, arg1, arg2, **kwargs):
+        pass
+
+    def method(self, arg1, arg2):
+        """docstring of Callable.method()."""
+        pass
+
+
+function = Callable()
+method = function.method
diff --git a/tests/roots/test-ext-autodoc/target/canonical/__init__.py b/tests/roots/test-ext-autodoc/target/canonical/__init__.py
new file mode 100644
index 0000000..4ca2b33
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/canonical/__init__.py
@@ -0,0 +1 @@
+from target.canonical.original import Bar, Foo
diff --git a/tests/roots/test-ext-autodoc/target/canonical/original.py b/tests/roots/test-ext-autodoc/target/canonical/original.py
new file mode 100644
index 0000000..42049b2
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/canonical/original.py
@@ -0,0 +1,15 @@
+class Foo:
+    """docstring"""
+
+    def meth(self):
+        """docstring"""
+
+
+def bar():
+    class Bar:
+        """docstring"""
+
+    return Bar
+
+
+Bar = bar()
diff --git a/tests/roots/test-ext-autodoc/target/classes.py b/tests/roots/test-ext-autodoc/target/classes.py
new file mode 100644
index 0000000..5ba0294
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/classes.py
@@ -0,0 +1,42 @@
+from inspect import Parameter, Signature
+from typing import List, Union
+
+
+class Foo:
+    pass
+
+
+class Bar:
+    def __init__(self, x, y):
+        pass
+
+
+class Baz:
+    def __new__(cls, x, y):
+        pass
+
+
+class Qux:
+    __signature__ = Signature(parameters=[Parameter('foo', Parameter.POSITIONAL_OR_KEYWORD),
+                                          Parameter('bar', Parameter.POSITIONAL_OR_KEYWORD)])
+
+    def __init__(self, x, y):
+        pass
+
+
+class Quux(List[Union[int, float]]):
+    """A subclass of List[Union[int, float]]"""
+    pass
+
+
+class Corge(Quux):
+    pass
+
+
+Alias = Foo
+
+#: docstring
+OtherAlias = Bar
+
+#: docstring
+IntAlias = int
diff --git a/tests/roots/test-ext-autodoc/target/coroutine.py b/tests/roots/test-ext-autodoc/target/coroutine.py
new file mode 100644
index 0000000..f977b6e
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/coroutine.py
@@ -0,0 +1,37 @@
+import asyncio
+from functools import wraps
+
+
+class AsyncClass:
+    async def do_coroutine(self):
+        """A documented coroutine function"""
+        attr_coro_result = await _other_coro_func()
+
+    @classmethod
+    async def do_coroutine2(cls):
+        """A documented coroutine classmethod"""
+        pass
+
+    @staticmethod
+    async def do_coroutine3():
+        """A documented coroutine staticmethod"""
+        pass
+
+    async def do_asyncgen(self):
+        """A documented async generator"""
+        yield
+
+
+async def _other_coro_func():
+    return "run"
+
+
+def myawait(f):
+    @wraps(f)
+    def wrapper(*args, **kwargs):
+        awaitable = f(*args, **kwargs)
+        return asyncio.run(awaitable)
+    return wrapper
+
+
+sync_func = myawait(_other_coro_func)
diff --git a/tests/roots/test-ext-autodoc/target/cython.pyx b/tests/roots/test-ext-autodoc/target/cython.pyx
new file mode 100644
index 0000000..5d0329a
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/cython.pyx
@@ -0,0 +1,13 @@
+# cython: binding=True
+# cython: language_level=3str
+
+def foo(x: int, *args, y: str, **kwargs):
+    """Docstring."""
+
+
+class Class:
+    """Docstring."""
+
+    def meth(self, name: str, age: int = 0) -> None:
+        """Docstring."""
+        pass
diff --git a/tests/roots/test-ext-autodoc/target/decorator.py b/tests/roots/test-ext-autodoc/target/decorator.py
new file mode 100644
index 0000000..faad3ff
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/decorator.py
@@ -0,0 +1,53 @@
+from functools import wraps
+
+
+def deco1(func):
+    """docstring for deco1"""
+    @wraps(func)
+    def wrapper():
+        return func()
+
+    return wrapper
+
+
+def deco2(condition, message):
+    """docstring for deco2"""
+    def decorator(func):
+        def wrapper():
+            return func()
+
+        return wrapper
+    return decorator
+
+
+@deco1
+def foo(name=None, age=None):
+    pass
+
+
+class Bar:
+    @deco1
+    def meth(self, name=None, age=None):
+        pass
+
+
+class Baz:
+    @deco1
+    def __init__(self, name=None, age=None):
+        pass
+
+
+class Qux:
+    @deco1
+    def __new__(self, name=None, age=None):
+        pass
+
+
+class _Metaclass(type):
+    @deco1
+    def __call__(self, name=None, age=None):
+        pass
+
+
+class Quux(metaclass=_Metaclass):
+    pass
diff --git a/tests/roots/test-ext-autodoc/target/descriptor.py b/tests/roots/test-ext-autodoc/target/descriptor.py
new file mode 100644
index 0000000..63d179b
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/descriptor.py
@@ -0,0 +1,31 @@
+class CustomDataDescriptor(object):
+    """Descriptor class docstring."""
+
+    def __init__(self, doc):
+        self.__doc__ = doc
+
+    def __get__(self, obj, type=None):
+        if obj is None:
+            return self
+        return 42
+
+    def meth(self):
+        """Function."""
+        return "The Answer"
+
+
+class CustomDataDescriptorMeta(type):
+    """Descriptor metaclass docstring."""
+
+
+class CustomDataDescriptor2(CustomDataDescriptor):
+    """Descriptor class with custom metaclass docstring."""
+    __metaclass__ = CustomDataDescriptorMeta
+
+
+class Class:
+    descr = CustomDataDescriptor("Descriptor instance docstring.")
+
+    @property
+    def prop(self):
+        """Property."""
diff --git a/tests/roots/test-ext-autodoc/target/docstring_signature.py b/tests/roots/test-ext-autodoc/target/docstring_signature.py
new file mode 100644
index 0000000..981d936
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/docstring_signature.py
@@ -0,0 +1,33 @@
+class A:
+    """A(foo, bar)"""
+
+
+class B:
+    """B(foo, bar)"""
+    def __init__(self):
+        """B(foo, bar, baz)"""
+
+
+class C:
+    """C(foo, bar)"""
+    def __new__(cls):
+        """C(foo, bar, baz)"""
+
+
+class D:
+    def __init__(self):
+        """D(foo, bar, baz)"""
+
+
+class E:
+    def __init__(self):
+        """E(foo: int, bar: int, baz: int) -> None \\
+        E(foo: str, bar: str, baz: str) -> None \\
+        E(foo: float, bar: float, baz: float)"""
+
+
+class F:
+    def __init__(self):
+        """F(foo: int, bar: int, baz: int) -> None
+        F(foo: str, bar: str, baz: str) -> None
+        F(foo: float, bar: float, baz: float)"""
diff --git a/tests/roots/test-ext-autodoc/target/empty_all.py b/tests/roots/test-ext-autodoc/target/empty_all.py
new file mode 100644
index 0000000..c094cff
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/empty_all.py
@@ -0,0 +1,16 @@
+"""
+docsting of empty_all module.
+"""
+__all__ = []
+
+
+def foo():
+    """docstring"""
+
+
+def bar():
+    """docstring"""
+
+
+def baz():
+    """docstring"""
diff --git a/tests/roots/test-ext-autodoc/target/enums.py b/tests/roots/test-ext-autodoc/target/enums.py
new file mode 100644
index 0000000..c69455f
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/enums.py
@@ -0,0 +1,23 @@
+import enum
+
+
+class EnumCls(enum.Enum):
+    """
+    this is enum class
+    """
+
+    #: doc for val1
+    val1 = 12
+    val2 = 23  #: doc for val2
+    val3 = 34
+    """doc for val3"""
+    val4 = 34
+
+    def say_hello(self):
+        """a method says hello to you."""
+        pass
+
+    @classmethod
+    def say_goodbye(cls):
+        """a classmethod says good-bye to you."""
+        pass
diff --git a/tests/roots/test-ext-autodoc/target/final.py b/tests/roots/test-ext-autodoc/target/final.py
new file mode 100644
index 0000000..ff78442
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/final.py
@@ -0,0 +1,14 @@
+import typing
+from typing import final
+
+
+@typing.final
+class Class:
+    """docstring"""
+
+    @final
+    def meth1(self):
+        """docstring"""
+
+    def meth2(self):
+        """docstring"""
diff --git a/tests/roots/test-ext-autodoc/target/functions.py b/tests/roots/test-ext-autodoc/target/functions.py
new file mode 100644
index 0000000..b62aa70
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/functions.py
@@ -0,0 +1,19 @@
+from functools import partial
+
+
+def func():
+    pass
+
+
+async def coroutinefunc():
+    pass
+
+
+async def asyncgenerator():
+    yield
+
+partial_func = partial(func)
+partial_coroutinefunc = partial(coroutinefunc)
+
+builtin_func = print
+partial_builtin_func = partial(print)
diff --git a/tests/roots/test-ext-autodoc/target/generic_class.py b/tests/roots/test-ext-autodoc/target/generic_class.py
new file mode 100644
index 0000000..e6ff38a
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/generic_class.py
@@ -0,0 +1,11 @@
+from typing import Generic, TypeVar
+
+T = TypeVar('T')
+
+
+# Test that typing.Generic's __new__ method does not mask our class'
+# __init__ signature.
+class A(Generic[T]):
+    """docstring for A"""
+    def __init__(self, a, b=None):
+        pass
diff --git a/tests/roots/test-ext-autodoc/target/genericalias.py b/tests/roots/test-ext-autodoc/target/genericalias.py
new file mode 100644
index 0000000..3856e03
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/genericalias.py
@@ -0,0 +1,14 @@
+from typing import Callable, List
+
+#: A list of int
+T = List[int]
+
+C = Callable[[int], None]  # a generic alias not having a doccomment
+
+
+class Class:
+    #: A list of int
+    T = List[int]
+
+#: A list of Class
+L = List[Class]
diff --git a/tests/roots/test-ext-autodoc/target/hide_value.py b/tests/roots/test-ext-autodoc/target/hide_value.py
new file mode 100644
index 0000000..1d53aab
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/hide_value.py
@@ -0,0 +1,19 @@
+#: docstring
+#:
+#: :meta hide-value:
+SENTINEL1 = object()
+
+#: :meta hide-value:
+SENTINEL2 = object()
+
+
+class Foo:
+    """docstring"""
+
+    #: docstring
+    #:
+    #: :meta hide-value:
+    SENTINEL1 = object()
+
+    #: :meta hide-value:
+    SENTINEL2 = object()
diff --git a/tests/roots/test-ext-autodoc/target/imported_members.py b/tests/roots/test-ext-autodoc/target/imported_members.py
new file mode 100644
index 0000000..ee6e5b3
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/imported_members.py
@@ -0,0 +1 @@
+from .partialfunction import func2, func3
diff --git a/tests/roots/test-ext-autodoc/target/inheritance.py b/tests/roots/test-ext-autodoc/target/inheritance.py
new file mode 100644
index 0000000..85d95cd
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/inheritance.py
@@ -0,0 +1,25 @@
+class Base(object):
+    #: docstring
+    inheritedattr = None
+
+    def inheritedmeth(self):
+        """Inherited function."""
+
+    @classmethod
+    def inheritedclassmeth(cls):
+        """Inherited class method."""
+
+    @staticmethod
+    def inheritedstaticmeth(cls):
+        """Inherited static method."""
+
+
+class Derived(Base):
+    def inheritedmeth(self):
+        # no docstring here
+        pass
+
+
+class MyList(list):
+    def meth(self):
+        """docstring"""
diff --git a/tests/roots/test-ext-autodoc/target/instance_variable.py b/tests/roots/test-ext-autodoc/target/instance_variable.py
new file mode 100644
index 0000000..1d393bc
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/instance_variable.py
@@ -0,0 +1,11 @@
+class Foo:
+    def __init__(self):
+        self.attr1 = None  #: docstring foo
+        self.attr2 = None  #: docstring foo
+
+
+class Bar(Foo):
+    def __init__(self):
+        self.attr2 = None  #: docstring bar
+        self.attr3 = None  #: docstring bar
+        self.attr4 = None
diff --git a/tests/roots/test-ext-autodoc/target/metadata.py b/tests/roots/test-ext-autodoc/target/metadata.py
new file mode 100644
index 0000000..7a4488f
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/metadata.py
@@ -0,0 +1,2 @@
+def foo():
+    """:meta metadata-only-docstring:"""
diff --git a/tests/roots/test-ext-autodoc/target/methods.py b/tests/roots/test-ext-autodoc/target/methods.py
new file mode 100644
index 0000000..ad5a6a9
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/methods.py
@@ -0,0 +1,29 @@
+from functools import partialmethod
+
+
+class Base():
+    def meth(self):
+        pass
+
+    @staticmethod
+    def staticmeth():
+        pass
+
+    @classmethod
+    def classmeth(cls):
+        pass
+
+    @property
+    def prop(self):
+        pass
+
+    partialmeth = partialmethod(meth)
+
+    async def coroutinemeth(self):
+        pass
+
+    partial_coroutinemeth = partialmethod(coroutinemeth)
+
+
+class Inherited(Base):
+    pass
diff --git a/tests/roots/test-ext-autodoc/target/module.py b/tests/roots/test-ext-autodoc/target/module.py
new file mode 100644
index 0000000..fe3b490
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/module.py
@@ -0,0 +1,14 @@
+undocumented = 1
+
+#: docstring
+documented = 1
+
+undoc_annotated: int
+
+#: docstring
+annotated: int
+
+__special__ = 1
+
+#: docstring
+__documented_special__ = 1
diff --git a/tests/roots/test-ext-autodoc/target/name_conflict/__init__.py b/tests/roots/test-ext-autodoc/target/name_conflict/__init__.py
new file mode 100644
index 0000000..0a6f496
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/name_conflict/__init__.py
@@ -0,0 +1,6 @@
+from .foo import bar
+
+
+class foo:
+    """docstring of target.name_conflict::foo."""
+    pass
diff --git a/tests/roots/test-ext-autodoc/target/name_conflict/foo.py b/tests/roots/test-ext-autodoc/target/name_conflict/foo.py
new file mode 100644
index 0000000..bb83ca0
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/name_conflict/foo.py
@@ -0,0 +1,2 @@
+class bar:
+    """docstring of target.name_conflict.foo::bar."""
diff --git a/tests/roots/test-ext-autodoc/target/name_mangling.py b/tests/roots/test-ext-autodoc/target/name_mangling.py
new file mode 100644
index 0000000..269b51d
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/name_mangling.py
@@ -0,0 +1,11 @@
+class Foo:
+    #: name of Foo
+    __name = None
+    __age = None
+
+
+class Bar(Foo):
+    __address = None
+
+    #: a member having mangled-like name
+    _Baz__email = None
diff --git a/tests/roots/test-ext-autodoc/target/need_mocks.py b/tests/roots/test-ext-autodoc/target/need_mocks.py
new file mode 100644
index 0000000..45b3ade
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/need_mocks.py
@@ -0,0 +1,43 @@
+
+import missing_module
+import missing_package1.missing_module1
+from missing_module import missing_name
+from missing_package2 import missing_module2
+from missing_package3.missing_module3 import missing_name
+
+import sphinx.missing_module4
+from sphinx.missing_module4 import missing_name2
+
+
+@missing_name(int)
+def decoratedFunction():
+    """decoratedFunction docstring"""
+    return None
+
+
+def func(arg: missing_module.Class):
+    """a function takes mocked object as an argument"""
+    pass
+
+
+class TestAutodoc(object):
+    """TestAutodoc docstring."""
+
+    #: docstring
+    Alias = missing_module2.Class
+
+    @missing_name
+    def decoratedMethod(self):
+        """TestAutodoc::decoratedMethod docstring"""
+        return None
+
+
+class Inherited(missing_module.Class):
+    """docstring"""
+    pass
+
+
+sphinx.missing_module4.missing_function(len(missing_name2))
+
+#: docstring
+Alias = missing_module2.Class
diff --git a/tests/roots/test-ext-autodoc/target/overload.py b/tests/roots/test-ext-autodoc/target/overload.py
new file mode 100644
index 0000000..1b395ee
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/overload.py
@@ -0,0 +1,88 @@
+from typing import Any, overload
+
+
+@overload
+def sum(x: int, y: int = 0) -> int:
+    ...
+
+
+@overload
+def sum(x: "float", y: "float" = 0.0) -> "float":
+    ...
+
+
+@overload
+def sum(x: str, y: str = ...) -> str:
+    ...
+
+
+def sum(x, y=None):
+    """docstring"""
+    return x + y
+
+
+class Math:
+    """docstring"""
+
+    @overload
+    def sum(self, x: int, y: int = 0) -> int:
+        ...
+
+    @overload
+    def sum(self, x: "float", y: "float" = 0.0) -> "float":
+        ...
+
+    @overload
+    def sum(self, x: str, y: str = ...) -> str:
+        ...
+
+    def sum(self, x, y=None):
+        """docstring"""
+        return x + y
+
+
+class Foo:
+    """docstring"""
+
+    @overload
+    def __new__(cls, x: int, y: int) -> "Foo":
+        ...
+
+    @overload
+    def __new__(cls, x: "str", y: "str") -> "Foo":
+        ...
+
+    def __new__(cls, x, y):
+        pass
+
+
+class Bar:
+    """docstring"""
+
+    @overload
+    def __init__(cls, x: int, y: int) -> None:
+        ...
+
+    @overload
+    def __init__(cls, x: "str", y: "str") -> "None":
+        ...
+
+    def __init__(cls, x, y):
+        pass
+
+
+class Meta(type):
+    @overload
+    def __call__(cls, x: int, y: int) -> Any:
+        ...
+
+    @overload
+    def __call__(cls, x: "str", y: "str") -> "Any":
+        ...
+
+    def __call__(cls, x, y):
+        pass
+
+
+class Baz(metaclass=Meta):
+    """docstring"""
diff --git a/tests/roots/test-ext-autodoc/target/overload2.py b/tests/roots/test-ext-autodoc/target/overload2.py
new file mode 100644
index 0000000..e901f79
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/overload2.py
@@ -0,0 +1,5 @@
+from target.overload import Bar
+
+
+class Baz(Bar):
+    pass
diff --git a/tests/roots/test-ext-autodoc/target/partialfunction.py b/tests/roots/test-ext-autodoc/target/partialfunction.py
new file mode 100644
index 0000000..3be63ee
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/partialfunction.py
@@ -0,0 +1,12 @@
+from functools import partial
+
+
+def func1(a, b, c):
+    """docstring of func1"""
+    pass
+
+
+func2 = partial(func1, 1)
+func3 = partial(func2, 2)
+func3.__doc__ = "docstring of func3"
+func4 = partial(func3, 3)
diff --git a/tests/roots/test-ext-autodoc/target/partialmethod.py b/tests/roots/test-ext-autodoc/target/partialmethod.py
new file mode 100644
index 0000000..4966a98
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/partialmethod.py
@@ -0,0 +1,18 @@
+# for py34 or above
+from functools import partialmethod
+
+
+class Cell(object):
+    """An example for partialmethod.
+
+    refs: https://docs.python.jp/3/library/functools.html#functools.partialmethod
+    """
+
+    def set_state(self, state):
+        """Update state of cell to *state*."""
+
+    #: Make a cell alive.
+    set_alive = partialmethod(set_state, True)
+
+    # a partialmethod with no docstring
+    set_dead = partialmethod(set_state, False)
diff --git a/tests/roots/test-ext-autodoc/target/pep570.py b/tests/roots/test-ext-autodoc/target/pep570.py
new file mode 100644
index 0000000..1a77eae
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/pep570.py
@@ -0,0 +1,11 @@
+def foo(*, a, b):
+    pass
+
+def bar(a, b, /, c, d):
+    pass
+
+def baz(a, /, *, b):
+    pass
+
+def qux(a, b, /):
+    pass
diff --git a/tests/roots/test-ext-autodoc/target/pep604.py b/tests/roots/test-ext-autodoc/target/pep604.py
new file mode 100644
index 0000000..9b1f94a
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/pep604.py
@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+attr: int | str  #: docstring
+
+
+def sum(x: int | str, y: int | str) -> int | str:
+    """docstring"""
+
+
+class Foo:
+    """docstring"""
+
+    attr: int | str  #: docstring
+
+    def meth(self, x: int | str, y: int | str) -> int | str:
+        """docstring"""
diff --git a/tests/roots/test-ext-autodoc/target/preserve_defaults.py b/tests/roots/test-ext-autodoc/target/preserve_defaults.py
new file mode 100644
index 0000000..0cc3b4e
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/preserve_defaults.py
@@ -0,0 +1,30 @@
+from datetime import datetime
+from typing import Any
+
+CONSTANT = 'foo'
+SENTINEL = object()
+
+
+def foo(name: str = CONSTANT,
+        sentinel: Any = SENTINEL,
+        now: datetime = datetime.now(),
+        color: int = 0xFFFFFF,
+        *,
+        kwarg1,
+        kwarg2 = 0xFFFFFF) -> None:
+    """docstring"""
+
+
+class Class:
+    """docstring"""
+
+    def meth(self, name: str = CONSTANT, sentinel: Any = SENTINEL,
+             now: datetime = datetime.now(), color: int = 0xFFFFFF,
+             *, kwarg1, kwarg2 = 0xFFFFFF) -> None:
+        """docstring"""
+
+    @classmethod
+    def clsmeth(cls, name: str = CONSTANT, sentinel: Any = SENTINEL,
+                now: datetime = datetime.now(), color: int = 0xFFFFFF,
+                *, kwarg1, kwarg2 = 0xFFFFFF) -> None:
+        """docstring"""
diff --git a/tests/roots/test-ext-autodoc/target/private.py b/tests/roots/test-ext-autodoc/target/private.py
new file mode 100644
index 0000000..e463448
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/private.py
@@ -0,0 +1,27 @@
+def private_function(name):
+    """private_function is a docstring().
+
+    :meta private:
+    """
+
+def _public_function(name):
+    """public_function is a docstring().
+
+    :meta public:
+    """
+
+
+PRIVATE_CONSTANT = None  #: :meta private:
+_PUBLIC_CONSTANT = None  #: :meta public:
+
+
+class Foo:
+    #: A public class attribute whose name starts with an underscore.
+    #:
+    #: :meta public:
+    _public_attribute = 47
+
+    #: A private class attribute whose name does not start with an underscore.
+    #:
+    #: :meta private:
+    private_attribute = 11
diff --git a/tests/roots/test-ext-autodoc/target/process_docstring.py b/tests/roots/test-ext-autodoc/target/process_docstring.py
new file mode 100644
index 0000000..6005943
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/process_docstring.py
@@ -0,0 +1,8 @@
+def func():
+    """
+    first line
+    ---
+    second line
+    ---
+    third line
+    """
diff --git a/tests/roots/test-ext-autodoc/target/properties.py b/tests/roots/test-ext-autodoc/target/properties.py
new file mode 100644
index 0000000..561daef
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/properties.py
@@ -0,0 +1,11 @@
+class Foo:
+    """docstring"""
+
+    @property
+    def prop1(self) -> int:
+        """docstring"""
+
+    @classmethod
+    @property
+    def prop2(self) -> int:
+        """docstring"""
diff --git a/tests/roots/test-ext-autodoc/target/singledispatch.py b/tests/roots/test-ext-autodoc/target/singledispatch.py
new file mode 100644
index 0000000..3dd5aaf
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/singledispatch.py
@@ -0,0 +1,36 @@
+import inspect
+from functools import singledispatch
+
+
+def assign_signature(func):
+    # This is intended to cover more complex signature-rewriting decorators.
+    func.__signature__ = inspect.signature(func)
+    return func
+
+
+@singledispatch
+def func(arg, kwarg=None):
+    """A function for general use."""
+    pass
+
+
+@func.register(int)
+@func.register(float)
+def _func_int(arg, kwarg=None):
+    """A function for int."""
+    pass
+
+
+@func.register(str)
+@assign_signature
+def _func_str(arg, kwarg=None):
+    """A function for str."""
+    pass
+
+
+@func.register
+def _func_dict(arg: dict, kwarg=None):
+    """A function for dict."""
+    # This function tests for specifying type through annotations
+    pass
+
diff --git a/tests/roots/test-ext-autodoc/target/singledispatchmethod.py b/tests/roots/test-ext-autodoc/target/singledispatchmethod.py
new file mode 100644
index 0000000..fb92293
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/singledispatchmethod.py
@@ -0,0 +1,27 @@
+from functools import singledispatchmethod
+
+
+class Foo:
+    """docstring"""
+
+    @singledispatchmethod
+    def meth(self, arg, kwarg=None):
+        """A method for general use."""
+        pass
+
+    @meth.register(int)
+    @meth.register(float)
+    def _meth_int(self, arg, kwarg=None):
+        """A method for int."""
+        pass
+
+    @meth.register(str)
+    def _meth_str(self, arg, kwarg=None):
+        """A method for str."""
+        pass
+
+    @meth.register
+    def _meth_dict(self, arg: dict, kwarg=None):
+        """A method for dict."""
+        # This function tests for specifying type through annotations
+        pass
diff --git a/tests/roots/test-ext-autodoc/target/slots.py b/tests/roots/test-ext-autodoc/target/slots.py
new file mode 100644
index 0000000..75c7a4a
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/slots.py
@@ -0,0 +1,22 @@
+class Foo:
+    """docstring"""
+
+    __slots__ = ['attr']
+
+
+class Bar:
+    """docstring"""
+
+    __slots__ = {'attr1': 'docstring of attr1',
+                 'attr2': 'docstring of attr2',
+                 'attr3': None}
+    __annotations__ = {'attr1': int}
+
+    def __init__(self):
+        self.attr2 = None  #: docstring of instance attr2
+
+
+class Baz:
+    """docstring"""
+
+    __slots__ = 'attr'
diff --git a/tests/roots/test-ext-autodoc/target/sort_by_all.py b/tests/roots/test-ext-autodoc/target/sort_by_all.py
new file mode 100644
index 0000000..03def47
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/sort_by_all.py
@@ -0,0 +1,25 @@
+__all__ = ['baz', 'foo', 'Bar']
+
+
+def foo():
+    pass
+
+
+class Bar:
+    pass
+
+
+def baz():
+    pass
+
+
+def qux():
+    pass
+
+
+class Quux:
+    pass
+
+
+def foobar():
+    pass
diff --git a/tests/roots/test-ext-autodoc/target/typed_vars.py b/tests/roots/test-ext-autodoc/target/typed_vars.py
new file mode 100644
index 0000000..f909b80
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/typed_vars.py
@@ -0,0 +1,34 @@
+#: attr1
+attr1: str = ''
+#: attr2
+attr2: str
+#: attr3
+attr3 = ''  # type: str
+
+
+class _Descriptor:
+    def __init__(self, name):
+        self.__doc__ = "This is {}".format(name)
+    def __get__(self):
+        pass
+
+
+class Class:
+    attr1: int = 0
+    attr2: int
+    attr3 = 0  # type: int
+
+    descr4: int = _Descriptor("descr4")
+
+    def __init__(self):
+        self.attr4: int = 0     #: attr4
+        self.attr5: int         #: attr5
+        self.attr6 = 0          # type: int
+        """attr6"""
+
+
+class Derived(Class):
+    attr7: int
+
+
+Alias = Derived
diff --git a/tests/roots/test-ext-autodoc/target/typehints.py b/tests/roots/test-ext-autodoc/target/typehints.py
new file mode 100644
index 0000000..4acfc89
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/typehints.py
@@ -0,0 +1,103 @@
+import pathlib
+from typing import Any, Tuple, TypeVar, Union
+
+CONST1: int
+#: docstring
+CONST2: int = 1
+#: docstring
+CONST3: pathlib.PurePosixPath = pathlib.PurePosixPath("/a/b/c")
+#: docstring
+T = TypeVar("T", bound=pathlib.PurePosixPath)
+
+
+def incr(a: int, b: int = 1) -> int:
+    return a + b
+
+
+def decr(a, b = 1):
+    # type: (int, int) -> int
+    return a - b
+
+
+class Math:
+    CONST1: int
+    CONST2: int = 1
+    CONST3: pathlib.PurePosixPath = pathlib.PurePosixPath("/a/b/c")
+
+    def __init__(self, s: str, o: Any = None) -> None:
+        pass
+
+    def incr(self, a: int, b: int = 1) -> int:
+        return a + b
+
+    def decr(self, a, b = 1):
+        # type: (int, int) -> int
+        return a - b
+
+    def nothing(self):
+        # type: () -> None
+        pass
+
+    def horse(self,
+              a,  # type: str
+              b,  # type: int
+              ):
+        # type: (...) -> None
+        return
+
+    @property
+    def prop(self) -> int:
+        return 0
+
+    @property
+    def path(self) -> pathlib.PurePosixPath:
+        return pathlib.PurePosixPath("/a/b/c")
+
+
+def tuple_args(x: Tuple[int, Union[int, str]]) -> Tuple[int, int]:
+    pass
+
+
+class NewAnnotation:
+    def __new__(cls, i: int) -> 'NewAnnotation':
+        pass
+
+
+class NewComment:
+    def __new__(cls, i):
+        # type: (int) -> NewComment
+        pass
+
+
+class _MetaclassWithCall(type):
+    def __call__(cls, a: int):
+        pass
+
+
+class SignatureFromMetaclass(metaclass=_MetaclassWithCall):
+    pass
+
+
+def complex_func(arg1, arg2, arg3=None, *args, **kwargs):
+    # type: (str, List[int], Tuple[int, Union[str, Unknown]], *str, **str) -> None
+    pass
+
+
+def missing_attr(c,
+                 a,  # type: str
+                 b=None  # type: Optional[str]
+                 ):
+    # type: (...) -> str
+    return a + (b or "")
+
+
+class _ClassWithDocumentedInit:
+    """Class docstring."""
+
+    def __init__(self, x: int, *args: int, **kwargs: int) -> None:
+        """Init docstring.
+
+        :param x: Some integer
+        :param args: Some integer
+        :param kwargs: Some integer
+        """
diff --git a/tests/roots/test-ext-autodoc/target/typevar.py b/tests/roots/test-ext-autodoc/target/typevar.py
new file mode 100644
index 0000000..ff2d46d
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/typevar.py
@@ -0,0 +1,30 @@
+from datetime import date
+from typing import NewType, TypeVar
+
+#: T1
+T1 = TypeVar("T1")
+
+T2 = TypeVar("T2")  # A TypeVar not having doc comment
+
+#: T3
+T3 = TypeVar("T3", int, str)
+
+#: T4
+T4 = TypeVar("T4", covariant=True)
+
+#: T5
+T5 = TypeVar("T5", contravariant=True)
+
+#: T6
+T6 = NewType("T6", date)
+
+#: T7
+T7 = TypeVar("T7", bound=int)
+
+
+class Class:
+    #: T1
+    T1 = TypeVar("T1")
+
+    #: T6
+    T6 = NewType("T6", date)
diff --git a/tests/roots/test-ext-autodoc/target/uninitialized_attributes.py b/tests/roots/test-ext-autodoc/target/uninitialized_attributes.py
new file mode 100644
index 0000000..e0f229c
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/uninitialized_attributes.py
@@ -0,0 +1,8 @@
+class Base:
+    attr1: int  #: docstring
+    attr2: str
+
+
+class Derived(Base):
+    attr3: int  #: docstring
+    attr4: str
diff --git a/tests/roots/test-ext-autodoc/target/wrappedfunction.py b/tests/roots/test-ext-autodoc/target/wrappedfunction.py
new file mode 100644
index 0000000..0bd2d20
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/wrappedfunction.py
@@ -0,0 +1,15 @@
+from contextlib import contextmanager
+from functools import lru_cache
+from typing import Generator
+
+
+@lru_cache(maxsize=None)
+def slow_function(message, timeout):
+    """This function is slow."""
+    print(message)
+
+
+@contextmanager
+def feeling_good(x: int, y: int) -> Generator:
+    """You'll feel better in this context!"""
+    yield