py2docfx 0.1.10.dev1859594__py3-none-any.whl → 0.1.10.dev1870645__py3-none-any.whl

py2docfx/venv/venv0/Lib/site-packages/sphinx/ext/autodoc/__init__.py

@@ -0,0 +1,2793 @@
+"""Extension to create automatic documentation from code docstrings.
+
+Automatically insert docstrings for functions, classes or whole modules into
+the doctree, thus avoiding duplication between docstrings and documentation
+for those who like elaborate docstrings.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from inspect import Parameter, Signature
+from types import ModuleType
+from typing import (TYPE_CHECKING, Any, Callable, Iterator, List, Sequence, Tuple, TypeVar,
+                    Union)
+
+from docutils.statemachine import StringList
+
+import sphinx
+from sphinx.application import Sphinx
+from sphinx.config import ENUM, Config
+from sphinx.environment import BuildEnvironment
+from sphinx.ext.autodoc.importer import get_class_members, import_module, import_object
+from sphinx.ext.autodoc.mock import ismock, mock, undecorate
+from sphinx.locale import _, __
+from sphinx.pycode import ModuleAnalyzer, PycodeError
+from sphinx.util import inspect, logging
+from sphinx.util.docstrings import prepare_docstring, separate_metadata
+from sphinx.util.inspect import (evaluate_signature, getdoc, object_description, safe_getattr,
+                                 stringify_signature)
+from sphinx.util.typing import OptionSpec, get_type_hints, restify, stringify_annotation
+
+if TYPE_CHECKING:
+    from sphinx.ext.autodoc.directive import DocumenterBridge
+
+logger = logging.getLogger(__name__)
+
+
+# This type isn't exposed directly in any modules, but can be found
+# here in most Python versions
+MethodDescriptorType = type(type.__subclasses__)
+
+
+#: extended signature RE: with explicit module name separated by ::
+py_ext_sig_re = re.compile(
+    r'''^ ([\w.]+::)?            # explicit module name
+          ([\w.]+\.)?            # module and/or class name(s)
+          (\w+)  \s*             # thing name
+          (?: \((.*)\)           # optional: arguments
+           (?:\s* -> \s* (.*))?  #           return annotation
+          )? $                   # and nothing more
+          ''', re.VERBOSE)
+special_member_re = re.compile(r'^__\S+__$')
+
+
+def identity(x: Any) -> Any:
+    return x
+
+
+class _All:
+    """A special value for :*-members: that matches to any member."""
+
+    def __contains__(self, item: Any) -> bool:
+        return True
+
+    def append(self, item: Any) -> None:
+        pass  # nothing
+
+
+class _Empty:
+    """A special value for :exclude-members: that never matches to any member."""
+
+    def __contains__(self, item: Any) -> bool:
+        return False
+
+
+ALL = _All()
+EMPTY = _Empty()
+UNINITIALIZED_ATTR = object()
+INSTANCEATTR = object()
+SLOTSATTR = object()
+
+
+def members_option(arg: Any) -> object | list[str]:
+    """Used to convert the :members: option to auto directives."""
+    if arg in (None, True):
+        return ALL
+    elif arg is False:
+        return None
+    else:
+        return [x.strip() for x in arg.split(',') if x.strip()]
+
+
+def exclude_members_option(arg: Any) -> object | set[str]:
+    """Used to convert the :exclude-members: option."""
+    if arg in (None, True):
+        return EMPTY
+    return {x.strip() for x in arg.split(',') if x.strip()}
+
+
+def inherited_members_option(arg: Any) -> set[str]:
+    """Used to convert the :inherited-members: option to auto directives."""
+    if arg in (None, True):
+        return {'object'}
+    elif arg:
+        return {x.strip() for x in arg.split(',')}
+    else:
+        return set()
+
+
+def member_order_option(arg: Any) -> str | None:
+    """Used to convert the :member-order: option to auto directives."""
+    if arg in (None, True):
+        return None
+    elif arg in ('alphabetical', 'bysource', 'groupwise'):
+        return arg
+    else:
+        raise ValueError(__('invalid value for member-order option: %s') % arg)
+
+
+def class_doc_from_option(arg: Any) -> str | None:
+    """Used to convert the :class-doc-from: option to autoclass directives."""
+    if arg in ('both', 'class', 'init'):
+        return arg
+    else:
+        raise ValueError(__('invalid value for class-doc-from option: %s') % arg)
+
+
+SUPPRESS = object()
+
+
+def annotation_option(arg: Any) -> Any:
+    if arg in (None, True):
+        # suppress showing the representation of the object
+        return SUPPRESS
+    else:
+        return arg
+
+
+def bool_option(arg: Any) -> bool:
+    """Used to convert flag options to auto directives.  (Instead of
+    directives.flag(), which returns None).
+    """
+    return True
+
+
+def merge_members_option(options: dict) -> None:
+    """Merge :private-members: and :special-members: options to the
+    :members: option.
+    """
+    if options.get('members') is ALL:
+        # merging is not needed when members: ALL
+        return
+
+    members = options.setdefault('members', [])
+    for key in {'private-members', 'special-members'}:
+        if key in options and options[key] not in (ALL, None):
+            for member in options[key]:
+                if member not in members:
+                    members.append(member)
+
+
+# Some useful event listener factories for autodoc-process-docstring.
+
+def cut_lines(pre: int, post: int = 0, what: str | None = None) -> Callable:
+    """Return a listener that removes the first *pre* and last *post*
+    lines of every docstring.  If *what* is a sequence of strings,
+    only docstrings of a type in *what* will be processed.
+
+    Use like this (e.g. in the ``setup()`` function of :file:`conf.py`)::
+
+       from sphinx.ext.autodoc import cut_lines
+       app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
+
+    This can (and should) be used in place of :confval:`automodule_skip_lines`.
+    """
+    def process(app: Sphinx, what_: str, name: str, obj: Any, options: Any, lines: list[str]
+                ) -> None:
+        if what and what_ not in what:
+            return
+        del lines[:pre]
+        if post:
+            # remove one trailing blank line.
+            if lines and not lines[-1]:
+                lines.pop(-1)
+            del lines[-post:]
+        # make sure there is a blank line at the end
+        if lines and lines[-1]:
+            lines.append('')
+    return process
+
+
+def between(
+    marker: str,
+    what: Sequence[str] | None = None,
+    keepempty: bool = False,
+    exclude: bool = False
+) -> Callable:
+    """Return a listener that either keeps, or if *exclude* is True excludes,
+    lines between lines that match the *marker* regular expression.  If no line
+    matches, the resulting docstring would be empty, so no change will be made
+    unless *keepempty* is true.
+
+    If *what* is a sequence of strings, only docstrings of a type in *what* will
+    be processed.
+    """
+    marker_re = re.compile(marker)
+
+    def process(app: Sphinx, what_: str, name: str, obj: Any, options: Any, lines: list[str]
+                ) -> None:
+        if what and what_ not in what:
+            return
+        deleted = 0
+        delete = not exclude
+        orig_lines = lines[:]
+        for i, line in enumerate(orig_lines):
+            if delete:
+                lines.pop(i - deleted)
+                deleted += 1
+            if marker_re.match(line):
+                delete = not delete
+                if delete:
+                    lines.pop(i - deleted)
+                    deleted += 1
+        if not lines and not keepempty:
+            lines[:] = orig_lines
+        # make sure there is a blank line at the end
+        if lines and lines[-1]:
+            lines.append('')
+    return process
+
+
+# This class is used only in ``sphinx.ext.autodoc.directive``,
+# But we define this class here to keep compatibility (see #4538)
+class Options(dict):
+    """A dict/attribute hybrid that returns None on nonexisting keys."""
+    def copy(self) -> Options:
+        return Options(super().copy())
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return self[name.replace('_', '-')]
+        except KeyError:
+            return None
+
+
+class ObjectMember(tuple):
+    """A member of object.
+
+    This is used for the result of `Documenter.get_module_members()` to
+    represent each member of the object.
+
+    .. Note::
+
+       An instance of this class behaves as a tuple of (name, object)
+       for compatibility to old Sphinx.  The behavior will be dropped
+       in the future.  Therefore extensions should not use the tuple
+       interface.
+    """
+
+    def __new__(cls, name: str, obj: Any, **kwargs: Any) -> Any:
+        return super().__new__(cls, (name, obj))  # type: ignore
+
+    def __init__(self, name: str, obj: Any, docstring: str | None = None,
+                 class_: Any = None, skipped: bool = False) -> None:
+        self.__name__ = name
+        self.object = obj
+        self.docstring = docstring
+        self.skipped = skipped
+        self.class_ = class_
+
+
+ObjectMembers = Union[List[ObjectMember], List[Tuple[str, Any]]]
+
+
+class Documenter:
+    """
+    A Documenter knows how to autodocument a single object type.  When
+    registered with the AutoDirective, it will be used to document objects
+    of that type when needed by autodoc.
+
+    Its *objtype* attribute selects what auto directive it is assigned to
+    (the directive name is 'auto' + objtype), and what directive it generates
+    by default, though that can be overridden by an attribute called
+    *directivetype*.
+
+    A Documenter has an *option_spec* that works like a docutils directive's;
+    in fact, it will be used to parse an auto directive's options that matches
+    the Documenter.
+    """
+    #: name by which the directive is called (auto...) and the default
+    #: generated directive name
+    objtype = 'object'
+    #: indentation by which to indent the directive content
+    content_indent = '   '
+    #: priority if multiple documenters return True from can_document_member
+    priority = 0
+    #: order if autodoc_member_order is set to 'groupwise'
+    member_order = 0
+    #: true if the generated content may contain titles
+    titles_allowed = False
+
+    option_spec: OptionSpec = {
+        'noindex': bool_option
+    }
+
+    def get_attr(self, obj: Any, name: str, *defargs: Any) -> Any:
+        """getattr() override for types such as Zope interfaces."""
+        return autodoc_attrgetter(self.env.app, obj, name, *defargs)
+
+    @classmethod
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
+                            ) -> bool:
+        """Called to see if a member can be documented by this Documenter."""
+        raise NotImplementedError('must be implemented in subclasses')
+
+    def __init__(self, directive: DocumenterBridge, name: str, indent: str = '') -> None:
+        self.directive = directive
+        self.config: Config = directive.env.config
+        self.env: BuildEnvironment = directive.env
+        self.options = directive.genopt
+        self.name = name
+        self.indent = indent
+        # the module and object path within the module, and the fully
+        # qualified name (all set after resolve_name succeeds)
+        self.modname: str = None
+        self.module: ModuleType = None
+        self.objpath: list[str] = None
+        self.fullname: str = None
+        # extra signature items (arguments and return annotation,
+        # also set after resolve_name succeeds)
+        self.args: str = None
+        self.retann: str = None
+        # the object to document (set after import_object succeeds)
+        self.object: Any = None
+        self.object_name: str = None
+        # the parent/owner of the object to document
+        self.parent: Any = None
+        # the module analyzer to get at attribute docs, or None
+        self.analyzer: ModuleAnalyzer = None
+
+    @property
+    def documenters(self) -> dict[str, type[Documenter]]:
+        """Returns registered Documenter classes"""
+        return self.env.app.registry.documenters
+
+    def add_line(self, line: str, source: str, *lineno: int) -> None:
+        """Append one line of generated reST to the output."""
+        if line.strip():  # not a blank line
+            self.directive.result.append(self.indent + line, source, *lineno)
+        else:
+            self.directive.result.append('', source, *lineno)
+
+    def resolve_name(self, modname: str, parents: Any, path: str, base: Any
+                     ) -> tuple[str, list[str]]:
+        """Resolve the module and name of the object to document given by the
+        arguments and the current module/class.
+
+        Must return a pair of the module name and a chain of attributes; for
+        example, it would return ``('zipfile', ['ZipFile', 'open'])`` for the
+        ``zipfile.ZipFile.open`` method.
+        """
+        raise NotImplementedError('must be implemented in subclasses')
+
+    def parse_name(self) -> bool:
+        """Determine what module to import and what attribute to document.
+
+        Returns True and sets *self.modname*, *self.objpath*, *self.fullname*,
+        *self.args* and *self.retann* if parsing and resolving was successful.
+        """
+        # first, parse the definition -- auto directives for classes and
+        # functions can contain a signature which is then used instead of
+        # an autogenerated one
+        try:
+            matched = py_ext_sig_re.match(self.name)
+            explicit_modname, path, base, args, retann = matched.groups()
+        except AttributeError:
+            logger.warning(__('invalid signature for auto%s (%r)') % (self.objtype, self.name),
+                           type='autodoc')
+            return False
+
+        # support explicit module and class name separation via ::
+        if explicit_modname is not None:
+            modname = explicit_modname[:-2]
+            parents = path.rstrip('.').split('.') if path else []
+        else:
+            modname = None
+            parents = []
+
+        with mock(self.config.autodoc_mock_imports):
+            self.modname, self.objpath = self.resolve_name(modname, parents, path, base)
+
+        if not self.modname:
+            return False
+
+        self.args = args
+        self.retann = retann
+        self.fullname = ((self.modname or '') +
+                         ('.' + '.'.join(self.objpath) if self.objpath else ''))
+        return True
+
+    def import_object(self, raiseerror: bool = False) -> bool:
+        """Import the object given by *self.modname* and *self.objpath* and set
+        it as *self.object*.
+
+        Returns True if successful, False if an error occurred.
+        """
+        with mock(self.config.autodoc_mock_imports):
+            try:
+                ret = import_object(self.modname, self.objpath, self.objtype,
+                                    attrgetter=self.get_attr,
+                                    warningiserror=self.config.autodoc_warningiserror)
+                self.module, self.parent, self.object_name, self.object = ret
+                if ismock(self.object):
+                    self.object = undecorate(self.object)
+                return True
+            except ImportError as exc:
+                if raiseerror:
+                    raise
+                else:
+                    logger.warning(exc.args[0], type='autodoc', subtype='import_object')
+                    self.env.note_reread()
+                    return False
+
+    def get_real_modname(self) -> str:
+        """Get the real module name of an object to document.
+
+        It can differ from the name of the module through which the object was
+        imported.
+        """
+        return self.get_attr(self.object, '__module__', None) or self.modname
+
+    def check_module(self) -> bool:
+        """Check if *self.object* is really defined in the module given by
+        *self.modname*.
+        """
+        if self.options.imported_members:
+            return True
+
+        subject = inspect.unpartial(self.object)
+        modname = self.get_attr(subject, '__module__', None)
+        if modname and modname != self.modname:
+            return False
+        return True
+
+    def format_args(self, **kwargs: Any) -> str | None:
+        """Format the argument signature of *self.object*.
+
+        Should return None if the object does not have a signature.
+        """
+        return None
+
+    def format_name(self) -> str:
+        """Format the name of *self.object*.
+
+        This normally should be something that can be parsed by the generated
+        directive, but doesn't need to be (Sphinx will display it unparsed
+        then).
+        """
+        # normally the name doesn't contain the module (except for module
+        # directives of course)
+        return '.'.join(self.objpath) or self.modname
+
+    def _call_format_args(self, **kwargs: Any) -> str | None:
+        if kwargs:
+            try:
+                return self.format_args(**kwargs)
+            except TypeError:
+                # avoid chaining exceptions, by putting nothing here
+                pass
+
+        # retry without arguments for old documenters
+        return self.format_args()
+
+    def format_signature(self, **kwargs: Any) -> str:
+        """Format the signature (arguments and return annotation) of the object.
+
+        Let the user process it via the ``autodoc-process-signature`` event.
+        """
+        if self.args is not None:
+            # signature given explicitly
+            args = "(%s)" % self.args
+            retann = self.retann
+        else:
+            # try to introspect the signature
+            try:
+                retann = None
+                args = self._call_format_args(**kwargs)
+                if args:
+                    matched = re.match(r'^(\(.*\))\s+->\s+(.*)$', args)
+                    if matched:
+                        args = matched.group(1)
+                        retann = matched.group(2)
+            except Exception as exc:
+                logger.warning(__('error while formatting arguments for %s: %s'),
+                               self.fullname, exc, type='autodoc')
+                args = None
+
+        result = self.env.events.emit_firstresult('autodoc-process-signature',
+                                                  self.objtype, self.fullname,
+                                                  self.object, self.options, args, retann)
+        if result:
+            args, retann = result
+
+        if args is not None:
+            return args + ((' -> %s' % retann) if retann else '')
+        else:
+            return ''
+
+    def add_directive_header(self, sig: str) -> None:
+        """Add the directive header and options to the generated content."""
+        domain = getattr(self, 'domain', 'py')
+        directive = getattr(self, 'directivetype', self.objtype)
+        name = self.format_name()
+        sourcename = self.get_sourcename()
+
+        # one signature per line, indented by column
+        prefix = f'.. {domain}:{directive}:: '
+        for i, sig_line in enumerate(sig.split("\n")):
+            self.add_line(f'{prefix}{name}{sig_line}',
+                          sourcename)
+            if i == 0:
+                prefix = " " * len(prefix)
+
+        if self.options.noindex:
+            self.add_line('   :noindex:', sourcename)
+        if self.objpath:
+            # Be explicit about the module, this is necessary since .. class::
+            # etc. don't support a prepended module name
+            self.add_line('   :module: %s' % self.modname, sourcename)
+
+    def get_doc(self) -> list[list[str]] | None:
+        """Decode and return lines of the docstring(s) for the object.
+
+        When it returns None, autodoc-process-docstring will not be called for this
+        object.
+        """
+        docstring = getdoc(self.object, self.get_attr, self.config.autodoc_inherit_docstrings,
+                           self.parent, self.object_name)
+        if docstring:
+            tab_width = self.directive.state.document.settings.tab_width
+            return [prepare_docstring(docstring, tab_width)]
+        return []
+
+    def process_doc(self, docstrings: list[list[str]]) -> Iterator[str]:
+        """Let the user process the docstrings before adding them."""
+        for docstringlines in docstrings:
+            if self.env.app:
+                # let extensions preprocess docstrings
+                self.env.app.emit('autodoc-process-docstring',
+                                  self.objtype, self.fullname, self.object,
+                                  self.options, docstringlines)
+
+                if docstringlines and docstringlines[-1] != '':
+                    # append a blank line to the end of the docstring
+                    docstringlines.append('')
+
+            yield from docstringlines
+
+    def get_sourcename(self) -> str:
+        if (inspect.safe_getattr(self.object, '__module__', None) and
+                inspect.safe_getattr(self.object, '__qualname__', None)):
+            # Get the correct location of docstring from self.object
+            # to support inherited methods
+            fullname = f'{self.object.__module__}.{self.object.__qualname__}'
+        else:
+            fullname = self.fullname
+
+        if self.analyzer:
+            return f'{self.analyzer.srcname}:docstring of {fullname}'
+        else:
+            return 'docstring of %s' % fullname
+
+    def add_content(self, more_content: StringList | None) -> None:
+        """Add content from docstrings, attribute documentation and user."""
+        docstring = True
+
+        # set sourcename and add content from attribute documentation
+        sourcename = self.get_sourcename()
+        if self.analyzer:
+            attr_docs = self.analyzer.find_attr_docs()
+            if self.objpath:
+                key = ('.'.join(self.objpath[:-1]), self.objpath[-1])
+                if key in attr_docs:
+                    docstring = False
+                    # make a copy of docstring for attributes to avoid cache
+                    # the change of autodoc-process-docstring event.
+                    docstrings = [list(attr_docs[key])]
+
+                    for i, line in enumerate(self.process_doc(docstrings)):
+                        self.add_line(line, sourcename, i)
+
+        # add content from docstrings
+        if docstring:
+            docstrings = self.get_doc()
+            if docstrings is None:
+                # Do not call autodoc-process-docstring on get_doc() returns None.
+                pass
+            else:
+                if not docstrings:
+                    # append at least a dummy docstring, so that the event
+                    # autodoc-process-docstring is fired and can add some
+                    # content if desired
+                    docstrings.append([])
+                for i, line in enumerate(self.process_doc(docstrings)):
+                    self.add_line(line, sourcename, i)
+
+        # add additional content (e.g. from document), if present
+        if more_content:
+            for line, src in zip(more_content.data, more_content.items):
+                self.add_line(line, src[0], src[1])
+
+    def get_object_members(self, want_all: bool) -> tuple[bool, ObjectMembers]:
+        """Return `(members_check_module, members)` where `members` is a
+        list of `(membername, member)` pairs of the members of *self.object*.
+
+        If *want_all* is True, return all members.  Else, only return those
+        members given by *self.options.members* (which may also be None).
+        """
+        raise NotImplementedError('must be implemented in subclasses')
+
+    def filter_members(self, members: ObjectMembers, want_all: bool
+                       ) -> list[tuple[str, Any, bool]]:
+        """Filter the given member list.
+
+        Members are skipped if
+
+        - they are private (except if given explicitly or the private-members
+          option is set)
+        - they are special methods (except if given explicitly or the
+          special-members option is set)
+        - they are undocumented (except if the undoc-members option is set)
+
+        The user can override the skipping decision by connecting to the
+        ``autodoc-skip-member`` event.
+        """
+        def is_filtered_inherited_member(name: str, obj: Any) -> bool:
+            inherited_members = self.options.inherited_members or set()
+
+            if inspect.isclass(self.object):
+                for cls in self.object.__mro__:
+                    if cls.__name__ in inherited_members and cls != self.object:
+                        # given member is a member of specified *super class*
+                        return True
+                    elif name in cls.__dict__:
+                        return False
+                    elif name in self.get_attr(cls, '__annotations__', {}):
+                        return False
+                    elif isinstance(obj, ObjectMember) and obj.class_ is cls:
+                        return False
+
+            return False
+
+        ret = []
+
+        # search for members in source code too
+        namespace = '.'.join(self.objpath)  # will be empty for modules
+
+        if self.analyzer:
+            attr_docs = self.analyzer.find_attr_docs()
+        else:
+            attr_docs = {}
+
+        # process members and determine which to skip
+        for obj in members:
+            try:
+                membername, member = obj
+                # if isattr is True, the member is documented as an attribute
+                if member is INSTANCEATTR:
+                    isattr = True
+                elif (namespace, membername) in attr_docs:
+                    isattr = True
+                else:
+                    isattr = False
+
+                doc = getdoc(member, self.get_attr, self.config.autodoc_inherit_docstrings,
+                             self.object, membername)
+                if not isinstance(doc, str):
+                    # Ignore non-string __doc__
+                    doc = None
+
+                # if the member __doc__ is the same as self's __doc__, it's just
+                # inherited and therefore not the member's doc
+                cls = self.get_attr(member, '__class__', None)
+                if cls:
+                    cls_doc = self.get_attr(cls, '__doc__', None)
+                    if cls_doc == doc:
+                        doc = None
+
+                if isinstance(obj, ObjectMember) and obj.docstring:
+                    # hack for ClassDocumenter to inject docstring via ObjectMember
+                    doc = obj.docstring
+
+                doc, metadata = separate_metadata(doc)
+                has_doc = bool(doc)
+
+                if 'private' in metadata:
+                    # consider a member private if docstring has "private" metadata
+                    isprivate = True
+                elif 'public' in metadata:
+                    # consider a member public if docstring has "public" metadata
+                    isprivate = False
+                else:
+                    isprivate = membername.startswith('_')
+
+                keep = False
+                if ismock(member) and (namespace, membername) not in attr_docs:
+                    # mocked module or object
+                    pass
+                elif (self.options.exclude_members and
+                      membername in self.options.exclude_members):
+                    # remove members given by exclude-members
+                    keep = False
+                elif want_all and special_member_re.match(membername):
+                    # special __methods__
+                    if (self.options.special_members and
+                            membername in self.options.special_members):
+                        if membername == '__doc__':
+                            keep = False
+                        elif is_filtered_inherited_member(membername, obj):
+                            keep = False
+                        else:
+                            keep = has_doc or self.options.undoc_members
+                    else:
+                        keep = False
+                elif (namespace, membername) in attr_docs:
+                    if want_all and isprivate:
+                        if self.options.private_members is None:
+                            keep = False
+                        else:
+                            keep = membername in self.options.private_members
+                    else:
+                        # keep documented attributes
+                        keep = True
+                elif want_all and isprivate:
+                    if has_doc or self.options.undoc_members:
+                        if self.options.private_members is None:
+                            keep = False
+                        elif is_filtered_inherited_member(membername, obj):
+                            keep = False
+                        else:
+                            keep = membername in self.options.private_members
+                    else:
+                        keep = False
+                else:
+                    if (self.options.members is ALL and
+                            is_filtered_inherited_member(membername, obj)):
+                        keep = False
+                    else:
+                        # ignore undocumented members if :undoc-members: is not given
+                        keep = has_doc or self.options.undoc_members
+
+                if isinstance(obj, ObjectMember) and obj.skipped:
+                    # forcedly skipped member (ex. a module attribute not defined in __all__)
+                    keep = False
+
+                # give the user a chance to decide whether this member
+                # should be skipped
+                if self.env.app:
+                    # let extensions preprocess docstrings
+                    skip_user = self.env.app.emit_firstresult(
+                        'autodoc-skip-member', self.objtype, membername, member,
+                        not keep, self.options)
+                    if skip_user is not None:
+                        keep = not skip_user
+            except Exception as exc:
+                logger.warning(__('autodoc: failed to determine %s.%s (%r) to be documented, '
+                                  'the following exception was raised:\n%s'),
+                               self.name, membername, member, exc, type='autodoc')
+                keep = False
+
+            if keep:
+                ret.append((membername, member, isattr))
+
+        return ret
+
+    def document_members(self, all_members: bool = False) -> None:
+        """Generate reST for member documentation.
+
+        If *all_members* is True, document all members, else those given by
+        *self.options.members*.
+        """
+        # set current namespace for finding members
+        self.env.temp_data['autodoc:module'] = self.modname
+        if self.objpath:
+            self.env.temp_data['autodoc:class'] = self.objpath[0]
+
+        want_all = (all_members or
+                    self.options.inherited_members or
+                    self.options.members is ALL)
+        # find out which members are documentable
+        members_check_module, members = self.get_object_members(want_all)
+
+        # document non-skipped members
+        memberdocumenters: list[tuple[Documenter, bool]] = []
+        for (mname, member, isattr) in self.filter_members(members, want_all):
+            classes = [cls for cls in self.documenters.values()
+                       if cls.can_document_member(member, mname, isattr, self)]
+            if not classes:
+                # don't know how to document this member
+                continue
+            # prefer the documenter with the highest priority
+            classes.sort(key=lambda cls: cls.priority)
+            # give explicitly separated module name, so that members
+            # of inner classes can be documented
+            full_mname = self.modname + '::' + '.'.join(self.objpath + [mname])
+            documenter = classes[-1](self.directive, full_mname, self.indent)
+            memberdocumenters.append((documenter, isattr))
+
+        member_order = self.options.member_order or self.config.autodoc_member_order
+        memberdocumenters = self.sort_members(memberdocumenters, member_order)
+
+        for documenter, isattr in memberdocumenters:
+            documenter.generate(
+                all_members=True, real_modname=self.real_modname,
+                check_module=members_check_module and not isattr)
+
+        # reset current objects
+        self.env.temp_data['autodoc:module'] = None
+        self.env.temp_data['autodoc:class'] = None
+
+    def sort_members(self, documenters: list[tuple[Documenter, bool]],
+                     order: str) -> list[tuple[Documenter, bool]]:
+        """Sort the given member list."""
+        if order == 'groupwise':
+            # sort by group; alphabetically within groups
+            documenters.sort(key=lambda e: (e[0].member_order, e[0].name))
+        elif order == 'bysource':
+            # By default, member discovery order matches source order,
+            # as dicts are insertion-ordered from Python 3.7.
+            if self.analyzer:
+                # sort by source order, by virtue of the module analyzer
+                tagorder = self.analyzer.tagorder
+
+                def keyfunc(entry: tuple[Documenter, bool]) -> int:
+                    fullname = entry[0].name.split('::')[1]
+                    return tagorder.get(fullname, len(tagorder))
+                documenters.sort(key=keyfunc)
+        else:  # alphabetical
+            documenters.sort(key=lambda e: e[0].name)
+
+        return documenters
+
+    def generate(
+        self,
+        more_content: StringList | None = None,
+        real_modname: str | None = None,
+        check_module: bool = False,
+        all_members: bool = False
+    ) -> None:
+        """Generate reST for the object given by *self.name*, and possibly for
+        its members.
+
+        If *more_content* is given, include that content. If *real_modname* is
+        given, use that module name to find attribute docs. If *check_module* is
+        True, only generate if the object is defined in the module name it is
+        imported from. If *all_members* is True, document all members.
+        """
+        if not self.parse_name():
+            # need a module to import
+            logger.warning(
+                __('don\'t know which module to import for autodocumenting '
+                   '%r (try placing a "module" or "currentmodule" directive '
+                   'in the document, or giving an explicit module name)') %
+                self.name, type='autodoc')
+            return
+
+        # now, import the module and get object to document
+        if not self.import_object():
+            return
+
+        # If there is no real module defined, figure out which to use.
+        # The real module is used in the module analyzer to look up the module
+        # where the attribute documentation would actually be found in.
+        # This is used for situations where you have a module that collects the
+        # functions and classes of internal submodules.
+        guess_modname = self.get_real_modname()
+        self.real_modname: str = real_modname or guess_modname
+
+        # try to also get a source code analyzer for attribute docs
+        try:
+            self.analyzer = ModuleAnalyzer.for_module(self.real_modname)
+            # parse right now, to get PycodeErrors on parsing (results will
+            # be cached anyway)
+            self.analyzer.find_attr_docs()
+        except PycodeError as exc:
+            logger.debug('[autodoc] module analyzer failed: %s', exc)
+            # no source file -- e.g. for builtin and C modules
+            self.analyzer = None
+            # at least add the module.__file__ as a dependency
+            if hasattr(self.module, '__file__') and self.module.__file__:
+                self.directive.record_dependencies.add(self.module.__file__)
+        else:
+            self.directive.record_dependencies.add(self.analyzer.srcname)
+
+        if self.real_modname != guess_modname:
+            # Add module to dependency list if target object is defined in other module.
+            try:
+                analyzer = ModuleAnalyzer.for_module(guess_modname)
+                self.directive.record_dependencies.add(analyzer.srcname)
+            except PycodeError:
+                pass
+
+        docstrings: list[str] = sum(self.get_doc() or [], [])
+        if ismock(self.object) and not docstrings:
+            logger.warning(__('A mocked object is detected: %r'),
+                           self.name, type='autodoc')
+
+        # check __module__ of object (for members not given explicitly)
+        if check_module:
+            if not self.check_module():
+                return
+
+        sourcename = self.get_sourcename()
+
+        # make sure that the result starts with an empty line.  This is
+        # necessary for some situations where another directive preprocesses
+        # reST and no starting newline is present
+        self.add_line('', sourcename)
+
+        # format the object's signature, if any
+        try:
+            sig = self.format_signature()
+        except Exception as exc:
+            logger.warning(__('error while formatting signature for %s: %s'),
+                           self.fullname, exc, type='autodoc')
+            return
+
+        # generate the directive header and options, if applicable
+        self.add_directive_header(sig)
+        self.add_line('', sourcename)
+
+        # e.g. the module directive doesn't have content
+        self.indent += self.content_indent
+
+        # add all content (from docstrings, attribute docs etc.)
+        self.add_content(more_content)
+
+        # document members, if possible
+        self.document_members(all_members)
+
+
+class ModuleDocumenter(Documenter):
+    """
+    Specialized Documenter subclass for modules.
+    """
+    objtype = 'module'
+    content_indent = ''
+    titles_allowed = True
+    _extra_indent = '   '
+
+    option_spec: OptionSpec = {
+        'members': members_option, 'undoc-members': bool_option,
+        'noindex': bool_option, 'inherited-members': inherited_members_option,
+        'show-inheritance': bool_option, 'synopsis': identity,
+        'platform': identity, 'deprecated': bool_option,
+        'member-order': member_order_option, 'exclude-members': exclude_members_option,
+        'private-members': members_option, 'special-members': members_option,
+        'imported-members': bool_option, 'ignore-module-all': bool_option,
+        'no-value': bool_option,
+    }
+
+    def __init__(self, *args: Any) -> None:
+        super().__init__(*args)
+        merge_members_option(self.options)
+        self.__all__: Sequence[str] | None = None
+
+    def add_content(self, more_content: StringList | None) -> None:
+        old_indent = self.indent
+        self.indent += self._extra_indent
+        super().add_content(None)
+        self.indent = old_indent
+        if more_content:
+            for line, src in zip(more_content.data, more_content.items):
+                self.add_line(line, src[0], src[1])
+
+    @classmethod
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
+                            ) -> bool:
+        # don't document submodules automatically
+        return False
+
+    def resolve_name(self, modname: str, parents: Any, path: str, base: Any
+                     ) -> tuple[str, list[str]]:
+        if modname is not None:
+            logger.warning(__('"::" in automodule name doesn\'t make sense'),
+                           type='autodoc')
+        return (path or '') + base, []
+
+    def parse_name(self) -> bool:
+        ret = super().parse_name()
+        if self.args or self.retann:
+            logger.warning(__('signature arguments or return annotation '
+                              'given for automodule %s') % self.fullname,
+                           type='autodoc')
+        return ret
+
+    def import_object(self, raiseerror: bool = False) -> bool:
+        ret = super().import_object(raiseerror)
+
+        try:
+            if not self.options.ignore_module_all:
+                self.__all__ = inspect.getall(self.object)
+        except ValueError as exc:
+            # invalid __all__ found.
+            logger.warning(__('__all__ should be a list of strings, not %r '
+                              '(in module %s) -- ignoring __all__') %
+                           (exc.args[0], self.fullname), type='autodoc')
+
+        return ret
+
+    def add_directive_header(self, sig: str) -> None:
+        Documenter.add_directive_header(self, sig)
+
+        sourcename = self.get_sourcename()
+
+        # add some module-specific options
+        if self.options.synopsis:
+            self.add_line('   :synopsis: ' + self.options.synopsis, sourcename)
+        if self.options.platform:
+            self.add_line('   :platform: ' + self.options.platform, sourcename)
+        if self.options.deprecated:
+            self.add_line('   :deprecated:', sourcename)
+
+    def get_module_members(self) -> dict[str, ObjectMember]:
+        """Get members of target module."""
+        if self.analyzer:
+            attr_docs = self.analyzer.attr_docs
+        else:
+            attr_docs = {}
+
+        members: dict[str, ObjectMember] = {}
+        for name in dir(self.object):
+            try:
+                value = safe_getattr(self.object, name, None)
+                if ismock(value):
+                    value = undecorate(value)
+                docstring = attr_docs.get(('', name), [])
+                members[name] = ObjectMember(name, value, docstring="\n".join(docstring))
+            except AttributeError:
+                continue
+
+        # annotation only member (ex. attr: int)
+        for name in inspect.getannotations(self.object):
+            if name not in members:
+                docstring = attr_docs.get(('', name), [])
+                members[name] = ObjectMember(name, INSTANCEATTR,
+                                             docstring="\n".join(docstring))
+
+        return members
+
+    def get_object_members(self, want_all: bool) -> tuple[bool, ObjectMembers]:
+        members = self.get_module_members()
+        if want_all:
+            if self.__all__ is None:
+                # for implicit module members, check __module__ to avoid
+                # documenting imported objects
+                return True, list(members.values())
+            else:
+                for member in members.values():
+                    if member.__name__ not in self.__all__:
+                        member.skipped = True
+
+                return False, list(members.values())
+        else:
+            memberlist = self.options.members or []
+            ret = []
+            for name in memberlist:
+                if name in members:
+                    ret.append(members[name])
+                else:
+                    logger.warning(__('missing attribute mentioned in :members: option: '
+                                      'module %s, attribute %s') %
+                                   (safe_getattr(self.object, '__name__', '???'), name),
+                                   type='autodoc')
+            return False, ret
+
+    def sort_members(self, documenters: list[tuple[Documenter, bool]],
+                     order: str) -> list[tuple[Documenter, bool]]:
+        if order == 'bysource' and self.__all__:
+            # Sort alphabetically first (for members not listed on the __all__)
+            documenters.sort(key=lambda e: e[0].name)
+
+            # Sort by __all__
+            def keyfunc(entry: tuple[Documenter, bool]) -> int:
+                name = entry[0].name.split('::')[1]
+                if self.__all__ and name in self.__all__:
+                    return self.__all__.index(name)
+                else:
+                    return len(self.__all__)
+            documenters.sort(key=keyfunc)
+
+            return documenters
+        else:
+            return super().sort_members(documenters, order)
+
+
+class ModuleLevelDocumenter(Documenter):
+    """
+    Specialized Documenter subclass for objects on module level (functions,
+    classes, data/constants).
+    """
+    def resolve_name(self, modname: str, parents: Any, path: str, base: Any
+                     ) -> tuple[str, list[str]]:
+        if modname is None:
+            if path:
+                modname = path.rstrip('.')
+            else:
+                # if documenting a toplevel object without explicit module,
+                # it can be contained in another auto directive ...
+                modname = self.env.temp_data.get('autodoc:module')
+                # ... or in the scope of a module directive
+                if not modname:
+                    modname = self.env.ref_context.get('py:module')
+                # ... else, it stays None, which means invalid
+        return modname, parents + [base]
+
+
+class ClassLevelDocumenter(Documenter):
+    """
+    Specialized Documenter subclass for objects on class level (methods,
+    attributes).
+    """
+    def resolve_name(self, modname: str, parents: Any, path: str, base: Any
+                     ) -> tuple[str, list[str]]:
+        if modname is None:
+            if path:
+                mod_cls = path.rstrip('.')
+            else:
+                mod_cls = None
+                # if documenting a class-level object without path,
+                # there must be a current class, either from a parent
+                # auto directive ...
+                mod_cls = self.env.temp_data.get('autodoc:class')
+                # ... or from a class directive
+                if mod_cls is None:
+                    mod_cls = self.env.ref_context.get('py:class')
+                # ... if still None, there's no way to know
+                if mod_cls is None:
+                    return None, []
+            modname, sep, cls = mod_cls.rpartition('.')
+            parents = [cls]
+            # if the module name is still missing, get it like above
+            if not modname:
+                modname = self.env.temp_data.get('autodoc:module')
+            if not modname:
+                modname = self.env.ref_context.get('py:module')
+            # ... else, it stays None, which means invalid
+        return modname, parents + [base]
+
+
+class DocstringSignatureMixin:
+    """
+    Mixin for FunctionDocumenter and MethodDocumenter to provide the
+    feature of reading the signature from the docstring.
+    """
+    _new_docstrings: list[list[str]] = None
+    _signatures: list[str] = None
+
+    def _find_signature(self) -> tuple[str | None, str | None]:
+        # candidates of the object name
+        valid_names = [self.objpath[-1]]  # type: ignore
+        if isinstance(self, ClassDocumenter):
+            valid_names.append('__init__')
+            if hasattr(self.object, '__mro__'):
+                valid_names.extend(cls.__name__ for cls in self.object.__mro__)
+
+        docstrings = self.get_doc()
+        if docstrings is None:
+            return None, None
+        self._new_docstrings = docstrings[:]
+        self._signatures = []
+        result = None
+        for i, doclines in enumerate(docstrings):
+            for j, line in enumerate(doclines):
+                if not line:
+                    # no lines in docstring, no match
+                    break
+
+                if line.endswith('\\'):
+                    line = line.rstrip('\\').rstrip()
+
+                # match first line of docstring against signature RE
+                match = py_ext_sig_re.match(line)
+                if not match:
+                    break
+                exmod, path, base, args, retann = match.groups()
+
+                # the base name must match ours
+                if base not in valid_names:
+                    break
+
+                # re-prepare docstring to ignore more leading indentation
+                tab_width = self.directive.state.document.settings.tab_width  # type: ignore
+                self._new_docstrings[i] = prepare_docstring('\n'.join(doclines[j + 1:]),
+                                                            tab_width)
+
+                if result is None:
+                    # first signature
+                    result = args, retann
+                else:
+                    # subsequent signatures
+                    self._signatures.append(f"({args}) -> {retann}")
+
+            if result:
+                # finish the loop when signature found
+                break
+
+        return result
+
+    def get_doc(self) -> list[list[str]]:
+        if self._new_docstrings is not None:
+            return self._new_docstrings
+        return super().get_doc()  # type: ignore[misc]
+
+    def format_signature(self, **kwargs: Any) -> str:
+        if self.args is None and self.config.autodoc_docstring_signature:  # type: ignore
+            # only act if a signature is not explicitly given already, and if
+            # the feature is enabled
+            result = self._find_signature()
+            if result is not None:
+                self.args, self.retann = result
+        sig = super().format_signature(**kwargs)  # type: ignore
+        if self._signatures:
+            return "\n".join([sig] + self._signatures)
+        else:
+            return sig
+
+
+class DocstringStripSignatureMixin(DocstringSignatureMixin):
+    """
+    Mixin for AttributeDocumenter to provide the
+    feature of stripping any function signature from the docstring.
+    """
+    def format_signature(self, **kwargs: Any) -> str:
+        if (
+            self.args is None
+            and self.config.autodoc_docstring_signature  # type: ignore[attr-defined]
+        ):
+            # only act if a signature is not explicitly given already, and if
+            # the feature is enabled
+            result = self._find_signature()
+            if result is not None:
+                # Discarding _args is a only difference with
+                # DocstringSignatureMixin.format_signature.
+                # Documenter.format_signature use self.args value to format.
+                _args, self.retann = result
+        return super().format_signature(**kwargs)
+
+
+class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type: ignore
+    """
+    Specialized Documenter subclass for functions.
+    """
+    objtype = 'function'
+    member_order = 30
+
+    @classmethod
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
+                            ) -> bool:
+        # supports functions, builtins and bound methods exported at the module level
+        return (inspect.isfunction(member) or inspect.isbuiltin(member) or
+                (inspect.isroutine(member) and isinstance(parent, ModuleDocumenter)))
+
+    def format_args(self, **kwargs: Any) -> str | None:
+        if self.config.autodoc_typehints in ('none', 'description'):
+            kwargs.setdefault('show_annotation', False)
+        if self.config.autodoc_typehints_format == "short":
+            kwargs.setdefault('unqualified_typehints', True)
+
+        try:
+            self.env.app.emit('autodoc-before-process-signature', self.object, False)
+            sig = inspect.signature(self.object, type_aliases=self.config.autodoc_type_aliases)
+            args = stringify_signature(sig, **kwargs)
+        except TypeError as exc:
+            logger.warning(__("Failed to get a function signature for %s: %s"),
+                           self.fullname, exc)
+            return None
+        except ValueError:
+            args = ''
+
+        if self.config.strip_signature_backslash:
+            # escape backslashes for reST
+            args = args.replace('\\', '\\\\')
+        return args
+
+    def document_members(self, all_members: bool = False) -> None:
+        pass
+
+    def add_directive_header(self, sig: str) -> None:
+        sourcename = self.get_sourcename()
+        super().add_directive_header(sig)
+
+        if inspect.iscoroutinefunction(self.object) or inspect.isasyncgenfunction(self.object):
+            self.add_line('   :async:', sourcename)
+
+    def format_signature(self, **kwargs: Any) -> str:
+        if self.config.autodoc_typehints_format == "short":
+            kwargs.setdefault('unqualified_typehints', True)
+
+        sigs = []
+        if (self.analyzer and
+                '.'.join(self.objpath) in self.analyzer.overloads and
+                self.config.autodoc_typehints != 'none'):
+            # Use signatures for overloaded functions instead of the implementation function.
+            overloaded = True
+        else:
+            overloaded = False
+            sig = super().format_signature(**kwargs)
+            sigs.append(sig)
+
+        if inspect.is_singledispatch_function(self.object):
+            # append signature of singledispatch'ed functions
+            for typ, func in self.object.registry.items():
+                if typ is object:
+                    pass  # default implementation. skipped.
+                else:
+                    dispatchfunc = self.annotate_to_first_argument(func, typ)
+                    if dispatchfunc:
+                        documenter = FunctionDocumenter(self.directive, '')
+                        documenter.object = dispatchfunc
+                        documenter.objpath = [None]
+                        sigs.append(documenter.format_signature())
+        if overloaded:
+            actual = inspect.signature(self.object,
+                                       type_aliases=self.config.autodoc_type_aliases)
+            __globals__ = safe_getattr(self.object, '__globals__', {})
+            for overload in self.analyzer.overloads.get('.'.join(self.objpath)):
+                overload = self.merge_default_value(actual, overload)
+                overload = evaluate_signature(overload, __globals__,
+                                              self.config.autodoc_type_aliases)
+
+                sig = stringify_signature(overload, **kwargs)
+                sigs.append(sig)
+
+        return "\n".join(sigs)
+
+    def merge_default_value(self, actual: Signature, overload: Signature) -> Signature:
+        """Merge default values of actual implementation to the overload variants."""
+        parameters = list(overload.parameters.values())
+        for i, param in enumerate(parameters):
+            actual_param = actual.parameters.get(param.name)
+            if actual_param and param.default == '...':
+                parameters[i] = param.replace(default=actual_param.default)
+
+        return overload.replace(parameters=parameters)
+
+    def annotate_to_first_argument(self, func: Callable, typ: type) -> Callable | None:
+        """Annotate type hint to the first argument of function if needed."""
+        try:
+            sig = inspect.signature(func, type_aliases=self.config.autodoc_type_aliases)
+        except TypeError as exc:
+            logger.warning(__("Failed to get a function signature for %s: %s"),
+                           self.fullname, exc)
+            return None
+        except ValueError:
+            return None
+
+        if len(sig.parameters) == 0:
+            return None
+
+        def dummy():
+            pass
+
+        params = list(sig.parameters.values())
+        if params[0].annotation is Parameter.empty:
+            params[0] = params[0].replace(annotation=typ)
+            try:
+                dummy.__signature__ = sig.replace(parameters=params)  # type: ignore
+                return dummy
+            except (AttributeError, TypeError):
+                # failed to update signature (ex. built-in or extension types)
+                return None
+
+        return func
+
+
+class DecoratorDocumenter(FunctionDocumenter):
+    """
+    Specialized Documenter subclass for decorator functions.
+    """
+    objtype = 'decorator'
+
+    # must be lower than FunctionDocumenter
+    priority = -1
+
+    def format_args(self, **kwargs: Any) -> Any:
+        args = super().format_args(**kwargs)
+        if ',' in args:
+            return args
+        else:
+            return None
+
+
+# Types which have confusing metaclass signatures it would be best not to show.
+# These are listed by name, rather than storing the objects themselves, to avoid
+# needing to import the modules.
+_METACLASS_CALL_BLACKLIST = [
+    'enum.EnumMeta.__call__',
+]
+
+
+# Types whose __new__ signature is a pass-through.
+_CLASS_NEW_BLACKLIST = [
+    'typing.Generic.__new__',
+]
+
+
+class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type: ignore
+    """
+    Specialized Documenter subclass for classes.
+    """
+    objtype = 'class'
+    member_order = 20
+    option_spec: OptionSpec = {
+        'members': members_option, 'undoc-members': bool_option,
+        'noindex': bool_option, 'inherited-members': inherited_members_option,
+        'show-inheritance': bool_option, 'member-order': member_order_option,
+        'exclude-members': exclude_members_option,
+        'private-members': members_option, 'special-members': members_option,
+        'class-doc-from': class_doc_from_option,
+    }
+
+    # Must be higher than FunctionDocumenter, ClassDocumenter, and
+    # AttributeDocumenter as NewType can be an attribute and is a class
+    # after Python 3.10. Before 3.10 it is a kind of function object
+    priority = 15
+
+    _signature_class: Any = None
+    _signature_method_name: str = None
+
+    def __init__(self, *args: Any) -> None:
+        super().__init__(*args)
+
+        if self.config.autodoc_class_signature == 'separated':
+            self.options = self.options.copy()
+
+            # show __init__() method
+            if self.options.special_members is None:
+                self.options['special-members'] = ['__new__', '__init__']
+            else:
+                self.options.special_members.append('__new__')
+                self.options.special_members.append('__init__')
+
+        merge_members_option(self.options)
+
+    @classmethod
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
+                            ) -> bool:
+        return isinstance(member, type) or (
+            isattr and (inspect.isNewType(member) or isinstance(member, TypeVar)))
+
+    def import_object(self, raiseerror: bool = False) -> bool:
+        ret = super().import_object(raiseerror)
+        # if the class is documented under another name, document it
+        # as data/attribute
+        if ret:
+            if hasattr(self.object, '__name__'):
+                self.doc_as_attr = (self.objpath[-1] != self.object.__name__)
+            else:
+                self.doc_as_attr = True
+            if inspect.isNewType(self.object) or isinstance(self.object, TypeVar):
+                modname = getattr(self.object, '__module__', self.modname)
+                if modname != self.modname and self.modname.startswith(modname):
+                    bases = self.modname[len(modname):].strip('.').split('.')
+                    self.objpath = bases + self.objpath
+                    self.modname = modname
+        return ret
+
+    def _get_signature(self) -> tuple[Any | None, str | None, Signature | None]:
+        if inspect.isNewType(self.object) or isinstance(self.object, TypeVar):
+            # Supress signature
+            return None, None, None
+
+        def get_user_defined_function_or_method(obj: Any, attr: str) -> Any:
+            """ Get the `attr` function or method from `obj`, if it is user-defined. """
+            if inspect.is_builtin_class_method(obj, attr):
+                return None
+            attr = self.get_attr(obj, attr, None)
+            if not (inspect.ismethod(attr) or inspect.isfunction(attr)):
+                return None
+            return attr
+
+        # This sequence is copied from inspect._signature_from_callable.
+        # ValueError means that no signature could be found, so we keep going.
+
+        # First, we check the obj has a __signature__ attribute
+        if (hasattr(self.object, '__signature__') and
+                isinstance(self.object.__signature__, Signature)):
+            return None, None, self.object.__signature__
+
+        # Next, let's see if it has an overloaded __call__ defined
+        # in its metaclass
+        call = get_user_defined_function_or_method(type(self.object), '__call__')
+
+        if call is not None:
+            if f"{call.__module__}.{call.__qualname__}" in _METACLASS_CALL_BLACKLIST:
+                call = None
+
+        if call is not None:
+            self.env.app.emit('autodoc-before-process-signature', call, True)
+            try:
+                sig = inspect.signature(call, bound_method=True,
+                                        type_aliases=self.config.autodoc_type_aliases)
+                return type(self.object), '__call__', sig
+            except ValueError:
+                pass
+
+        # Now we check if the 'obj' class has a '__new__' method
+        new = get_user_defined_function_or_method(self.object, '__new__')
+
+        if new is not None:
+            if f"{new.__module__}.{new.__qualname__}" in _CLASS_NEW_BLACKLIST:
+                new = None
+
+        if new is not None:
+            self.env.app.emit('autodoc-before-process-signature', new, True)
+            try:
+                sig = inspect.signature(new, bound_method=True,
+                                        type_aliases=self.config.autodoc_type_aliases)
+                return self.object, '__new__', sig
+            except ValueError:
+                pass
+
+        # Finally, we should have at least __init__ implemented
+        init = get_user_defined_function_or_method(self.object, '__init__')
+        if init is not None:
+            self.env.app.emit('autodoc-before-process-signature', init, True)
+            try:
+                sig = inspect.signature(init, bound_method=True,
+                                        type_aliases=self.config.autodoc_type_aliases)
+                return self.object, '__init__', sig
+            except ValueError:
+                pass
+
+        # None of the attributes are user-defined, so fall back to let inspect
+        # handle it.
+        # We don't know the exact method that inspect.signature will read
+        # the signature from, so just pass the object itself to our hook.
+        self.env.app.emit('autodoc-before-process-signature', self.object, False)
+        try:
+            sig = inspect.signature(self.object, bound_method=False,
+                                    type_aliases=self.config.autodoc_type_aliases)
+            return None, None, sig
+        except ValueError:
+            pass
+
+        # Still no signature: happens e.g. for old-style classes
+        # with __init__ in C and no `__text_signature__`.
+        return None, None, None
+
+    def format_args(self, **kwargs: Any) -> str | None:
+        if self.config.autodoc_typehints in ('none', 'description'):
+            kwargs.setdefault('show_annotation', False)
+        if self.config.autodoc_typehints_format == "short":
+            kwargs.setdefault('unqualified_typehints', True)
+
+        try:
+            self._signature_class, self._signature_method_name, sig = self._get_signature()
+        except TypeError as exc:
+            # __signature__ attribute contained junk
+            logger.warning(__("Failed to get a constructor signature for %s: %s"),
+                           self.fullname, exc)
+            return None
+
+        if sig is None:
+            return None
+
+        return stringify_signature(sig, show_return_annotation=False, **kwargs)
+
+    def _find_signature(self) -> tuple[str, str]:
+        result = super()._find_signature()
+        if result is not None:
+            # Strip a return value from signature of constructor in docstring (first entry)
+            result = (result[0], None)
+
+        for i, sig in enumerate(self._signatures):
+            if sig.endswith(' -> None'):
+                # Strip a return value from signatures of constructor in docstring (subsequent
+                # entries)
+                self._signatures[i] = sig[:-8]
+
+        return result
+
+    def format_signature(self, **kwargs: Any) -> str:
+        if self.doc_as_attr:
+            return ''
+        if self.config.autodoc_class_signature == 'separated':
+            # do not show signatures
+            return ''
+
+        if self.config.autodoc_typehints_format == "short":
+            kwargs.setdefault('unqualified_typehints', True)
+
+        sig = super().format_signature()
+        sigs = []
+
+        overloads = self.get_overloaded_signatures()
+        if overloads and self.config.autodoc_typehints != 'none':
+            # Use signatures for overloaded methods instead of the implementation method.
+            method = safe_getattr(self._signature_class, self._signature_method_name, None)
+            __globals__ = safe_getattr(method, '__globals__', {})
+            for overload in overloads:
+                overload = evaluate_signature(overload, __globals__,
+                                              self.config.autodoc_type_aliases)
+
+                parameters = list(overload.parameters.values())
+                overload = overload.replace(parameters=parameters[1:],
+                                            return_annotation=Parameter.empty)
+                sig = stringify_signature(overload, **kwargs)
+                sigs.append(sig)
+        else:
+            sigs.append(sig)
+
+        return "\n".join(sigs)
+
+    def get_overloaded_signatures(self) -> list[Signature]:
+        if self._signature_class and self._signature_method_name:
+            for cls in self._signature_class.__mro__:
+                try:
+                    analyzer = ModuleAnalyzer.for_module(cls.__module__)
+                    analyzer.analyze()
+                    qualname = '.'.join([cls.__qualname__, self._signature_method_name])
+                    if qualname in analyzer.overloads:
+                        return analyzer.overloads.get(qualname, [])
+                    elif qualname in analyzer.tagorder:
+                        # the constructor is defined in the class, but not overridden.
+                        return []
+                except PycodeError:
+                    pass
+
+        return []
+
+    def get_canonical_fullname(self) -> str | None:
+        __modname__ = safe_getattr(self.object, '__module__', self.modname)
+        __qualname__ = safe_getattr(self.object, '__qualname__', None)
+        if __qualname__ is None:
+            __qualname__ = safe_getattr(self.object, '__name__', None)
+        if __qualname__ and '<locals>' in __qualname__:
+            # No valid qualname found if the object is defined as locals
+            __qualname__ = None
+
+        if __modname__ and __qualname__:
+            return '.'.join([__modname__, __qualname__])
+        else:
+            return None
+
+    def add_directive_header(self, sig: str) -> None:
+        sourcename = self.get_sourcename()
+
+        if self.doc_as_attr:
+            self.directivetype = 'attribute'
+        super().add_directive_header(sig)
+
+        if inspect.isNewType(self.object) or isinstance(self.object, TypeVar):
+            return
+
+        if self.analyzer and '.'.join(self.objpath) in self.analyzer.finals:
+            self.add_line('   :final:', sourcename)
+
+        canonical_fullname = self.get_canonical_fullname()
+        if (not self.doc_as_attr and not inspect.isNewType(self.object)
+                and canonical_fullname and self.fullname != canonical_fullname):
+            self.add_line('   :canonical: %s' % canonical_fullname, sourcename)
+
+        # add inheritance info, if wanted
+        if not self.doc_as_attr and self.options.show_inheritance:
+            if inspect.getorigbases(self.object):
+                # A subclass of generic types
+                # refs: PEP-560 <https://peps.python.org/pep-0560/>
+                bases = list(self.object.__orig_bases__)
+            elif hasattr(self.object, '__bases__') and len(self.object.__bases__):
+                # A normal class
+                bases = list(self.object.__bases__)
+            else:
+                bases = []
+
+            self.env.events.emit('autodoc-process-bases',
+                                 self.fullname, self.object, self.options, bases)
+
+            if self.config.autodoc_typehints_format == "short":
+                base_classes = [restify(cls, "smart") for cls in bases]
+            else:
+                base_classes = [restify(cls) for cls in bases]
+
+            sourcename = self.get_sourcename()
+            self.add_line('', sourcename)
+            self.add_line('   ' + _('Bases: %s') % ', '.join(base_classes), sourcename)
+
+    def get_object_members(self, want_all: bool) -> tuple[bool, ObjectMembers]:
+        members = get_class_members(self.object, self.objpath, self.get_attr,
+                                    self.config.autodoc_inherit_docstrings)
+        if not want_all:
+            if not self.options.members:
+                return False, []  # type: ignore
+            # specific members given
+            selected = []
+            for name in self.options.members:
+                if name in members:
+                    selected.append(members[name])
+                else:
+                    logger.warning(__('missing attribute %s in object %s') %
+                                   (name, self.fullname), type='autodoc')
+            return False, selected
+        elif self.options.inherited_members:
+            return False, list(members.values())
+        else:
+            return False, [m for m in members.values() if m.class_ == self.object]
+
+    def get_doc(self) -> list[list[str]] | None:
+        if isinstance(self.object, TypeVar):
+            if self.object.__doc__ == TypeVar.__doc__:
+                return []
+        if sys.version_info[:2] < (3, 10):
+            if inspect.isNewType(self.object) or isinstance(self.object, TypeVar):
+                parts = self.modname.strip('.').split('.')
+                orig_objpath = self.objpath
+                for i in range(len(parts)):
+                    new_modname = '.'.join(parts[:len(parts) - i])
+                    new_objpath = parts[len(parts) - i:] + orig_objpath
+                    try:
+                        analyzer = ModuleAnalyzer.for_module(new_modname)
+                        analyzer.analyze()
+                        key = ('', new_objpath[-1])
+                        comment = list(analyzer.attr_docs.get(key, []))
+                        if comment:
+                            self.objpath = new_objpath
+                            self.modname = new_modname
+                            return [comment]
+                    except PycodeError:
+                        pass
+        if self.doc_as_attr:
+            # Don't show the docstring of the class when it is an alias.
+            comment = self.get_variable_comment()
+            if comment:
+                return []
+            else:
+                return None
+
+        lines = getattr(self, '_new_docstrings', None)
+        if lines is not None:
+            return lines
+
+        classdoc_from = self.options.get('class-doc-from', self.config.autoclass_content)
+
+        docstrings = []
+        attrdocstring = getdoc(self.object, self.get_attr)
+        if attrdocstring:
+            docstrings.append(attrdocstring)
+
+        # for classes, what the "docstring" is can be controlled via a
+        # config value; the default is only the class docstring
+        if classdoc_from in ('both', 'init'):
+            __init__ = self.get_attr(self.object, '__init__', None)
+            initdocstring = getdoc(__init__, self.get_attr,
+                                   self.config.autodoc_inherit_docstrings,
+                                   self.object, '__init__')
+            # for new-style classes, no __init__ means default __init__
+            if (initdocstring is not None and
+                (initdocstring == object.__init__.__doc__ or  # for pypy
+                 initdocstring.strip() == object.__init__.__doc__)):  # for !pypy
+                initdocstring = None
+            if not initdocstring:
+                # try __new__
+                __new__ = self.get_attr(self.object, '__new__', None)
+                initdocstring = getdoc(__new__, self.get_attr,
+                                       self.config.autodoc_inherit_docstrings,
+                                       self.object, '__new__')
+                # for new-style classes, no __new__ means default __new__
+                if (initdocstring is not None and
+                    (initdocstring == object.__new__.__doc__ or  # for pypy
+                     initdocstring.strip() == object.__new__.__doc__)):  # for !pypy
+                    initdocstring = None
+            if initdocstring:
+                if classdoc_from == 'init':
+                    docstrings = [initdocstring]
+                else:
+                    docstrings.append(initdocstring)
+
+        tab_width = self.directive.state.document.settings.tab_width
+        return [prepare_docstring(docstring, tab_width) for docstring in docstrings]
+
+    def get_variable_comment(self) -> list[str] | None:
+        try:
+            key = ('', '.'.join(self.objpath))
+            if self.doc_as_attr:
+                analyzer = ModuleAnalyzer.for_module(self.modname)
+            else:
+                analyzer = ModuleAnalyzer.for_module(self.get_real_modname())
+            analyzer.analyze()
+            return list(analyzer.attr_docs.get(key, []))
+        except PycodeError:
+            return None
+
+    def add_content(self, more_content: StringList | None) -> None:
+        if inspect.isNewType(self.object):
+            if self.config.autodoc_typehints_format == "short":
+                supertype = restify(self.object.__supertype__, "smart")
+            else:
+                supertype = restify(self.object.__supertype__)
+
+            more_content = StringList([_('alias of %s') % supertype, ''], source='')
+        if isinstance(self.object, TypeVar):
+            attrs = [repr(self.object.__name__)]
+            for constraint in self.object.__constraints__:
+                if self.config.autodoc_typehints_format == "short":
+                    attrs.append(stringify_annotation(constraint, "smart"))
+                else:
+                    attrs.append(stringify_annotation(constraint))
+            if self.object.__bound__:
+                if self.config.autodoc_typehints_format == "short":
+                    bound = restify(self.object.__bound__, "smart")
+                else:
+                    bound = restify(self.object.__bound__)
+                attrs.append(r"bound=\ " + bound)
+            if self.object.__covariant__:
+                attrs.append("covariant=True")
+            if self.object.__contravariant__:
+                attrs.append("contravariant=True")
+
+            more_content = StringList(
+                [_('alias of TypeVar(%s)') % ", ".join(attrs), ''],
+                source=''
+            )
+        if self.doc_as_attr and self.modname != self.get_real_modname():
+            try:
+                # override analyzer to obtain doccomment around its definition.
+                self.analyzer = ModuleAnalyzer.for_module(self.modname)
+                self.analyzer.analyze()
+            except PycodeError:
+                pass
+
+        if self.doc_as_attr and not self.get_variable_comment():
+            try:
+                if self.config.autodoc_typehints_format == "short":
+                    alias = restify(self.object, "smart")
+                else:
+                    alias = restify(self.object)
+                more_content = StringList([_('alias of %s') % alias], source='')
+            except AttributeError:
+                pass  # Invalid class object is passed.
+
+        super().add_content(more_content)
+
+    def document_members(self, all_members: bool = False) -> None:
+        if self.doc_as_attr:
+            return
+        super().document_members(all_members)
+
+    def generate(
+        self,
+        more_content: StringList | None = None,
+        real_modname: str | None = None,
+        check_module: bool = False,
+        all_members: bool = False
+    ) -> None:
+        # Do not pass real_modname and use the name from the __module__
+        # attribute of the class.
+        # If a class gets imported into the module real_modname
+        # the analyzer won't find the source of the class, if
+        # it looks in real_modname.
+        return super().generate(more_content=more_content,
+                                check_module=check_module,
+                                all_members=all_members)
+
+
+class ExceptionDocumenter(ClassDocumenter):
+    """
+    Specialized ClassDocumenter subclass for exceptions.
+    """
+    objtype = 'exception'
+    member_order = 10
+
+    # needs a higher priority than ClassDocumenter
+    priority = ClassDocumenter.priority + 5
+
+    @classmethod
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
+                            ) -> bool:
+        return isinstance(member, type) and issubclass(member, BaseException)
+
+
+class DataDocumenterMixinBase:
+    # define types of instance variables
+    config: Config = None
+    env: BuildEnvironment = None
+    modname: str = None
+    parent: Any = None
+    object: Any = None
+    objpath: list[str] = None
+
+    def should_suppress_directive_header(self) -> bool:
+        """Check directive header should be suppressed."""
+        return False
+
+    def should_suppress_value_header(self) -> bool:
+        """Check :value: header should be suppressed."""
+        return False
+
+    def update_content(self, more_content: StringList) -> None:
+        """Update docstring, for example with TypeVar variance."""
+        pass
+
+
+class GenericAliasMixin(DataDocumenterMixinBase):
+    """
+    Mixin for DataDocumenter and AttributeDocumenter to provide the feature for
+    supporting GenericAliases.
+    """
+
+    def should_suppress_directive_header(self) -> bool:
+        return (inspect.isgenericalias(self.object) or
+                super().should_suppress_directive_header())
+
+    def update_content(self, more_content: StringList) -> None:
+        if inspect.isgenericalias(self.object):
+            if self.config.autodoc_typehints_format == "short":
+                alias = restify(self.object, "smart")
+            else:
+                alias = restify(self.object)
+
+            more_content.append(_('alias of %s') % alias, '')
+            more_content.append('', '')
+
+        super().update_content(more_content)
+
+
+class UninitializedGlobalVariableMixin(DataDocumenterMixinBase):
+    """
+    Mixin for DataDocumenter to provide the feature for supporting uninitialized
+    (type annotation only) global variables.
+    """
+
+    def import_object(self, raiseerror: bool = False) -> bool:
+        try:
+            return super().import_object(raiseerror=True)  # type: ignore
+        except ImportError as exc:
+            # annotation only instance variable (PEP-526)
+            try:
+                with mock(self.config.autodoc_mock_imports):
+                    parent = import_module(self.modname, self.config.autodoc_warningiserror)
+                    annotations = get_type_hints(parent, None,
+                                                 self.config.autodoc_type_aliases)
+                    if self.objpath[-1] in annotations:
+                        self.object = UNINITIALIZED_ATTR
+                        self.parent = parent
+                        return True
+            except ImportError:
+                pass
+
+            if raiseerror:
+                raise
+            else:
+                logger.warning(exc.args[0], type='autodoc', subtype='import_object')
+                self.env.note_reread()
+                return False
+
+    def should_suppress_value_header(self) -> bool:
+        return (self.object is UNINITIALIZED_ATTR or
+                super().should_suppress_value_header())
+
+    def get_doc(self) -> list[list[str]] | None:
+        if self.object is UNINITIALIZED_ATTR:
+            return []
+        else:
+            return super().get_doc()  # type: ignore
+
+
+class DataDocumenter(GenericAliasMixin,
+                     UninitializedGlobalVariableMixin, ModuleLevelDocumenter):
+    """
+    Specialized Documenter subclass for data items.
+    """
+    objtype = 'data'
+    member_order = 40
+    priority = -10
+    option_spec: OptionSpec = dict(ModuleLevelDocumenter.option_spec)
+    option_spec["annotation"] = annotation_option
+    option_spec["no-value"] = bool_option
+
+    @classmethod
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
+                            ) -> bool:
+        return isinstance(parent, ModuleDocumenter) and isattr
+
+    def update_annotations(self, parent: Any) -> None:
+        """Update __annotations__ to support type_comment and so on."""
+        annotations = dict(inspect.getannotations(parent))
+        parent.__annotations__ = annotations
+
+        try:
+            analyzer = ModuleAnalyzer.for_module(self.modname)
+            analyzer.analyze()
+            for (classname, attrname), annotation in analyzer.annotations.items():
+                if classname == '' and attrname not in annotations:
+                    annotations[attrname] = annotation
+        except PycodeError:
+            pass
+
+    def import_object(self, raiseerror: bool = False) -> bool:
+        ret = super().import_object(raiseerror)
+        if self.parent:
+            self.update_annotations(self.parent)
+
+        return ret
+
+    def should_suppress_value_header(self) -> bool:
+        if super().should_suppress_value_header():
+            return True
+        else:
+            doc = self.get_doc()
+            docstring, metadata = separate_metadata('\n'.join(sum(doc, [])))
+            if 'hide-value' in metadata:
+                return True
+
+        return False
+
+    def add_directive_header(self, sig: str) -> None:
+        super().add_directive_header(sig)
+        sourcename = self.get_sourcename()
+        if self.options.annotation is SUPPRESS or self.should_suppress_directive_header():
+            pass
+        elif self.options.annotation:
+            self.add_line('   :annotation: %s' % self.options.annotation,
+                          sourcename)
+        else:
+            if self.config.autodoc_typehints != 'none':
+                # obtain annotation for this data
+                annotations = get_type_hints(self.parent, None,
+                                             self.config.autodoc_type_aliases)
+                if self.objpath[-1] in annotations:
+                    if self.config.autodoc_typehints_format == "short":
+                        objrepr = stringify_annotation(annotations.get(self.objpath[-1]),
+                                                       "smart")
+                    else:
+                        objrepr = stringify_annotation(annotations.get(self.objpath[-1]),
+                                                       "fully-qualified-except-typing")
+                    self.add_line('   :type: ' + objrepr, sourcename)
+
+            try:
+                if (self.options.no_value or self.should_suppress_value_header() or
+                        ismock(self.object)):
+                    pass
+                else:
+                    objrepr = object_description(self.object)
+                    self.add_line('   :value: ' + objrepr, sourcename)
+            except ValueError:
+                pass
+
+    def document_members(self, all_members: bool = False) -> None:
+        pass
+
+    def get_real_modname(self) -> str:
+        real_modname = self.get_attr(self.parent or self.object, '__module__', None)
+        return real_modname or self.modname
+
+    def get_module_comment(self, attrname: str) -> list[str] | None:
+        try:
+            analyzer = ModuleAnalyzer.for_module(self.modname)
+            analyzer.analyze()
+            key = ('', attrname)
+            if key in analyzer.attr_docs:
+                return list(analyzer.attr_docs[key])
+        except PycodeError:
+            pass
+
+        return None
+
+    def get_doc(self) -> list[list[str]] | None:
+        # Check the variable has a docstring-comment
+        comment = self.get_module_comment(self.objpath[-1])
+        if comment:
+            return [comment]
+        else:
+            return super().get_doc()
+
+    def add_content(self, more_content: StringList | None) -> None:
+        # Disable analyzing variable comment on Documenter.add_content() to control it on
+        # DataDocumenter.add_content()
+        self.analyzer = None
+
+        if not more_content:
+            more_content = StringList()
+
+        self.update_content(more_content)
+        super().add_content(more_content)
+
+
+class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter):  # type: ignore
+    """
+    Specialized Documenter subclass for methods (normal, static and class).
+    """
+    objtype = 'method'
+    directivetype = 'method'
+    member_order = 50
+    priority = 1  # must be more than FunctionDocumenter
+
+    @classmethod
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
+                            ) -> bool:
+        return inspect.isroutine(member) and not isinstance(parent, ModuleDocumenter)
+
+    def import_object(self, raiseerror: bool = False) -> bool:
+        ret = super().import_object(raiseerror)
+        if not ret:
+            return ret
+
+        # to distinguish classmethod/staticmethod
+        obj = self.parent.__dict__.get(self.object_name)
+        if obj is None:
+            obj = self.object
+
+        if (inspect.isclassmethod(obj) or
+                inspect.isstaticmethod(obj, cls=self.parent, name=self.object_name)):
+            # document class and static members before ordinary ones
+            self.member_order = self.member_order - 1
+
+        return ret
+
+    def format_args(self, **kwargs: Any) -> str | None:
+        if self.config.autodoc_typehints in ('none', 'description'):
+            kwargs.setdefault('show_annotation', False)
+        if self.config.autodoc_typehints_format == "short":
+            kwargs.setdefault('unqualified_typehints', True)
+
+        try:
+            if self.object == object.__init__ and self.parent != object:
+                # Classes not having own __init__() method are shown as no arguments.
+                #
+                # Note: The signature of object.__init__() is (self, /, *args, **kwargs).
+                #       But it makes users confused.
+                args = '()'
+            else:
+                if inspect.isstaticmethod(self.object, cls=self.parent, name=self.object_name):
+                    self.env.app.emit('autodoc-before-process-signature', self.object, False)
+                    sig = inspect.signature(self.object, bound_method=False,
+                                            type_aliases=self.config.autodoc_type_aliases)
+                else:
+                    self.env.app.emit('autodoc-before-process-signature', self.object, True)
+                    sig = inspect.signature(self.object, bound_method=True,
+                                            type_aliases=self.config.autodoc_type_aliases)
+                args = stringify_signature(sig, **kwargs)
+        except TypeError as exc:
+            logger.warning(__("Failed to get a method signature for %s: %s"),
+                           self.fullname, exc)
+            return None
+        except ValueError:
+            args = ''
+
+        if self.config.strip_signature_backslash:
+            # escape backslashes for reST
+            args = args.replace('\\', '\\\\')
+        return args
+
+    def add_directive_header(self, sig: str) -> None:
+        super().add_directive_header(sig)
+
+        sourcename = self.get_sourcename()
+        obj = self.parent.__dict__.get(self.object_name, self.object)
+        if inspect.isabstractmethod(obj):
+            self.add_line('   :abstractmethod:', sourcename)
+        if inspect.iscoroutinefunction(obj) or inspect.isasyncgenfunction(obj):
+            self.add_line('   :async:', sourcename)
+        if inspect.isclassmethod(obj):
+            self.add_line('   :classmethod:', sourcename)
+        if inspect.isstaticmethod(obj, cls=self.parent, name=self.object_name):
+            self.add_line('   :staticmethod:', sourcename)
+        if self.analyzer and '.'.join(self.objpath) in self.analyzer.finals:
+            self.add_line('   :final:', sourcename)
+
+    def document_members(self, all_members: bool = False) -> None:
+        pass
+
+    def format_signature(self, **kwargs: Any) -> str:
+        if self.config.autodoc_typehints_format == "short":
+            kwargs.setdefault('unqualified_typehints', True)
+
+        sigs = []
+        if (self.analyzer and
+                '.'.join(self.objpath) in self.analyzer.overloads and
+                self.config.autodoc_typehints != 'none'):
+            # Use signatures for overloaded methods instead of the implementation method.
+            overloaded = True
+        else:
+            overloaded = False
+            sig = super().format_signature(**kwargs)
+            sigs.append(sig)
+
+        meth = self.parent.__dict__.get(self.objpath[-1])
+        if inspect.is_singledispatch_method(meth):
+            # append signature of singledispatch'ed functions
+            for typ, func in meth.dispatcher.registry.items():
+                if typ is object:
+                    pass  # default implementation. skipped.
+                else:
+                    dispatchmeth = self.annotate_to_first_argument(func, typ)
+                    if dispatchmeth:
+                        documenter = MethodDocumenter(self.directive, '')
+                        documenter.parent = self.parent
+                        documenter.object = dispatchmeth
+                        documenter.objpath = [None]
+                        sigs.append(documenter.format_signature())
+        if overloaded:
+            if inspect.isstaticmethod(self.object, cls=self.parent, name=self.object_name):
+                actual = inspect.signature(self.object, bound_method=False,
+                                           type_aliases=self.config.autodoc_type_aliases)
+            else:
+                actual = inspect.signature(self.object, bound_method=True,
+                                           type_aliases=self.config.autodoc_type_aliases)
+
+            __globals__ = safe_getattr(self.object, '__globals__', {})
+            for overload in self.analyzer.overloads.get('.'.join(self.objpath)):
+                overload = self.merge_default_value(actual, overload)
+                overload = evaluate_signature(overload, __globals__,
+                                              self.config.autodoc_type_aliases)
+
+                if not inspect.isstaticmethod(self.object, cls=self.parent,
+                                              name=self.object_name):
+                    parameters = list(overload.parameters.values())
+                    overload = overload.replace(parameters=parameters[1:])
+                sig = stringify_signature(overload, **kwargs)
+                sigs.append(sig)
+
+        return "\n".join(sigs)
+
+    def merge_default_value(self, actual: Signature, overload: Signature) -> Signature:
+        """Merge default values of actual implementation to the overload variants."""
+        parameters = list(overload.parameters.values())
+        for i, param in enumerate(parameters):
+            actual_param = actual.parameters.get(param.name)
+            if actual_param and param.default == '...':
+                parameters[i] = param.replace(default=actual_param.default)
+
+        return overload.replace(parameters=parameters)
+
+    def annotate_to_first_argument(self, func: Callable, typ: type) -> Callable | None:
+        """Annotate type hint to the first argument of function if needed."""
+        try:
+            sig = inspect.signature(func, type_aliases=self.config.autodoc_type_aliases)
+        except TypeError as exc:
+            logger.warning(__("Failed to get a method signature for %s: %s"),
+                           self.fullname, exc)
+            return None
+        except ValueError:
+            return None
+
+        if len(sig.parameters) == 1:
+            return None
+
+        def dummy():
+            pass
+
+        params = list(sig.parameters.values())
+        if params[1].annotation is Parameter.empty:
+            params[1] = params[1].replace(annotation=typ)
+            try:
+                dummy.__signature__ = sig.replace(parameters=params)  # type: ignore
+                return dummy
+            except (AttributeError, TypeError):
+                # failed to update signature (ex. built-in or extension types)
+                return None
+
+        return func
+
+    def get_doc(self) -> list[list[str]] | None:
+        if self._new_docstrings is not None:
+            # docstring already returned previously, then modified by
+            # `DocstringSignatureMixin`.  Just return the previously-computed
+            # result, so that we don't lose the processing done by
+            # `DocstringSignatureMixin`.
+            return self._new_docstrings
+        if self.objpath[-1] == '__init__':
+            docstring = getdoc(self.object, self.get_attr,
+                               self.config.autodoc_inherit_docstrings,
+                               self.parent, self.object_name)
+            if (docstring is not None and
+                (docstring == object.__init__.__doc__ or  # for pypy
+                 docstring.strip() == object.__init__.__doc__)):  # for !pypy
+                docstring = None
+            if docstring:
+                tab_width = self.directive.state.document.settings.tab_width
+                return [prepare_docstring(docstring, tabsize=tab_width)]
+            else:
+                return []
+        elif self.objpath[-1] == '__new__':
+            docstring = getdoc(self.object, self.get_attr,
+                               self.config.autodoc_inherit_docstrings,
+                               self.parent, self.object_name)
+            if (docstring is not None and
+                (docstring == object.__new__.__doc__ or  # for pypy
+                 docstring.strip() == object.__new__.__doc__)):  # for !pypy
+                docstring = None
+            if docstring:
+                tab_width = self.directive.state.document.settings.tab_width
+                return [prepare_docstring(docstring, tabsize=tab_width)]
+            else:
+                return []
+        else:
+            return super().get_doc()
+
+
+class NonDataDescriptorMixin(DataDocumenterMixinBase):
+    """
+    Mixin for AttributeDocumenter to provide the feature for supporting non
+    data-descriptors.
+
+    .. note:: This mix-in must be inherited after other mix-ins.  Otherwise, docstring
+              and :value: header will be suppressed unexpectedly.
+    """
+
+    def import_object(self, raiseerror: bool = False) -> bool:
+        ret = super().import_object(raiseerror)  # type: ignore
+        if ret and not inspect.isattributedescriptor(self.object):
+            self.non_data_descriptor = True
+        else:
+            self.non_data_descriptor = False
+
+        return ret
+
+    def should_suppress_value_header(self) -> bool:
+        return (not getattr(self, 'non_data_descriptor', False) or
+                super().should_suppress_directive_header())
+
+    def get_doc(self) -> list[list[str]] | None:
+        if getattr(self, 'non_data_descriptor', False):
+            # the docstring of non datadescriptor is very probably the wrong thing
+            # to display
+            return None
+        else:
+            return super().get_doc()  # type: ignore
+
+
+class SlotsMixin(DataDocumenterMixinBase):
+    """
+    Mixin for AttributeDocumenter to provide the feature for supporting __slots__.
+    """
+
+    def isslotsattribute(self) -> bool:
+        """Check the subject is an attribute in __slots__."""
+        try:
+            __slots__ = inspect.getslots(self.parent)
+            return bool(__slots__) and self.objpath[-1] in __slots__
+        except (ValueError, TypeError):
+            return False
+
+    def import_object(self, raiseerror: bool = False) -> bool:
+        ret = super().import_object(raiseerror)  # type: ignore
+        if self.isslotsattribute():
+            self.object = SLOTSATTR
+
+        return ret
+
+    def should_suppress_value_header(self) -> bool:
+        if self.object is SLOTSATTR:
+            return True
+        else:
+            return super().should_suppress_value_header()
+
+    def get_doc(self) -> list[list[str]] | None:
+        if self.object is SLOTSATTR:
+            try:
+                __slots__ = inspect.getslots(self.parent)
+                if __slots__ and __slots__.get(self.objpath[-1]):
+                    docstring = prepare_docstring(__slots__[self.objpath[-1]])
+                    return [docstring]
+                else:
+                    return []
+            except ValueError as exc:
+                logger.warning(__('Invalid __slots__ found on %s. Ignored.'),
+                               (self.parent.__qualname__, exc), type='autodoc')
+                return []
+        else:
+            return super().get_doc()  # type: ignore
+
+
+class RuntimeInstanceAttributeMixin(DataDocumenterMixinBase):
+    """
+    Mixin for AttributeDocumenter to provide the feature for supporting runtime
+    instance attributes (that are defined in __init__() methods with doc-comments).
+
+    Example:
+
+        class Foo:
+            def __init__(self):
+                self.attr = None  #: This is a target of this mix-in.
+    """
+
+    RUNTIME_INSTANCE_ATTRIBUTE = object()
+
+    def is_runtime_instance_attribute(self, parent: Any) -> bool:
+        """Check the subject is an attribute defined in __init__()."""
+        # An instance variable defined in __init__().
+        if self.get_attribute_comment(parent, self.objpath[-1]):  # type: ignore
+            return True
+        elif self.is_runtime_instance_attribute_not_commented(parent):
+            return True
+        else:
+            return False
+
+    def is_runtime_instance_attribute_not_commented(self, parent: Any) -> bool:
+        """Check the subject is an attribute defined in __init__() without comment."""
+        for cls in inspect.getmro(parent):
+            try:
+                module = safe_getattr(cls, '__module__')
+                qualname = safe_getattr(cls, '__qualname__')
+
+                analyzer = ModuleAnalyzer.for_module(module)
+                analyzer.analyze()
+                if qualname and self.objpath:
+                    key = '.'.join([qualname, self.objpath[-1]])
+                    if key in analyzer.tagorder:
+                        return True
+            except (AttributeError, PycodeError):
+                pass
+
+        return None
+
+    def import_object(self, raiseerror: bool = False) -> bool:
+        """Check the existence of runtime instance attribute after failing to import the
+        attribute."""
+        try:
+            return super().import_object(raiseerror=True)  # type: ignore
+        except ImportError as exc:
+            try:
+                with mock(self.config.autodoc_mock_imports):
+                    ret = import_object(self.modname, self.objpath[:-1], 'class',
+                                        attrgetter=self.get_attr,  # type: ignore
+                                        warningiserror=self.config.autodoc_warningiserror)
+                    parent = ret[3]
+                    if self.is_runtime_instance_attribute(parent):
+                        self.object = self.RUNTIME_INSTANCE_ATTRIBUTE
+                        self.parent = parent
+                        return True
+            except ImportError:
+                pass
+
+            if raiseerror:
+                raise
+            else:
+                logger.warning(exc.args[0], type='autodoc', subtype='import_object')
+                self.env.note_reread()
+                return False
+
+    def should_suppress_value_header(self) -> bool:
+        return (self.object is self.RUNTIME_INSTANCE_ATTRIBUTE or
+                super().should_suppress_value_header())
+
+    def get_doc(self) -> list[list[str]] | None:
+        if (self.object is self.RUNTIME_INSTANCE_ATTRIBUTE and
+                self.is_runtime_instance_attribute_not_commented(self.parent)):
+            return None
+        else:
+            return super().get_doc()  # type: ignore
+
+
+class UninitializedInstanceAttributeMixin(DataDocumenterMixinBase):
+    """
+    Mixin for AttributeDocumenter to provide the feature for supporting uninitialized
+    instance attributes (PEP-526 styled, annotation only attributes).
+
+    Example:
+
+        class Foo:
+            attr: int  #: This is a target of this mix-in.
+    """
+
+    def is_uninitialized_instance_attribute(self, parent: Any) -> bool:
+        """Check the subject is an annotation only attribute."""
+        annotations = get_type_hints(parent, None, self.config.autodoc_type_aliases)
+        return self.objpath[-1] in annotations
+
+    def import_object(self, raiseerror: bool = False) -> bool:
+        """Check the exisitence of uninitialized instance attribute when failed to import
+        the attribute."""
+        try:
+            return super().import_object(raiseerror=True)  # type: ignore
+        except ImportError as exc:
+            try:
+                ret = import_object(self.modname, self.objpath[:-1], 'class',
+                                    attrgetter=self.get_attr,  # type: ignore
+                                    warningiserror=self.config.autodoc_warningiserror)
+                parent = ret[3]
+                if self.is_uninitialized_instance_attribute(parent):
+                    self.object = UNINITIALIZED_ATTR
+                    self.parent = parent
+                    return True
+            except ImportError:
+                pass
+
+            if raiseerror:
+                raise
+            else:
+                logger.warning(exc.args[0], type='autodoc', subtype='import_object')
+                self.env.note_reread()
+                return False
+
+    def should_suppress_value_header(self) -> bool:
+        return (self.object is UNINITIALIZED_ATTR or
+                super().should_suppress_value_header())
+
+    def get_doc(self) -> list[list[str]] | None:
+        if self.object is UNINITIALIZED_ATTR:
+            return None
+        else:
+            return super().get_doc()  # type: ignore
+
+
+class AttributeDocumenter(GenericAliasMixin, SlotsMixin,  # type: ignore
+                          RuntimeInstanceAttributeMixin,
+                          UninitializedInstanceAttributeMixin, NonDataDescriptorMixin,
+                          DocstringStripSignatureMixin, ClassLevelDocumenter):
+    """
+    Specialized Documenter subclass for attributes.
+    """
+    objtype = 'attribute'
+    member_order = 60
+    option_spec: OptionSpec = dict(ModuleLevelDocumenter.option_spec)
+    option_spec["annotation"] = annotation_option
+    option_spec["no-value"] = bool_option
+
+    # must be higher than the MethodDocumenter, else it will recognize
+    # some non-data descriptors as methods
+    priority = 10
+
+    @staticmethod
+    def is_function_or_method(obj: Any) -> bool:
+        return inspect.isfunction(obj) or inspect.isbuiltin(obj) or inspect.ismethod(obj)
+
+    @classmethod
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
+                            ) -> bool:
+        if isinstance(parent, ModuleDocumenter):
+            return False
+        elif inspect.isattributedescriptor(member):
+            return True
+        elif not inspect.isroutine(member) and not isinstance(member, type):
+            return True
+        else:
+            return False
+
+    def document_members(self, all_members: bool = False) -> None:
+        pass
+
+    def update_annotations(self, parent: Any) -> None:
+        """Update __annotations__ to support type_comment and so on."""
+        try:
+            annotations = dict(inspect.getannotations(parent))
+            parent.__annotations__ = annotations
+
+            for cls in inspect.getmro(parent):
+                try:
+                    module = safe_getattr(cls, '__module__')
+                    qualname = safe_getattr(cls, '__qualname__')
+
+                    analyzer = ModuleAnalyzer.for_module(module)
+                    analyzer.analyze()
+                    for (classname, attrname), annotation in analyzer.annotations.items():
+                        if classname == qualname and attrname not in annotations:
+                            annotations[attrname] = annotation
+                except (AttributeError, PycodeError):
+                    pass
+        except (AttributeError, TypeError):
+            # Failed to set __annotations__ (built-in, extensions, etc.)
+            pass
+
+    def import_object(self, raiseerror: bool = False) -> bool:
+        ret = super().import_object(raiseerror)
+        if inspect.isenumattribute(self.object):
+            self.object = self.object.value
+        if self.parent:
+            self.update_annotations(self.parent)
+
+        return ret
+
+    def get_real_modname(self) -> str:
+        real_modname = self.get_attr(self.parent or self.object, '__module__', None)
+        return real_modname or self.modname
+
+    def should_suppress_value_header(self) -> bool:
+        if super().should_suppress_value_header():
+            return True
+        else:
+            doc = self.get_doc()
+            if doc:
+                docstring, metadata = separate_metadata('\n'.join(sum(doc, [])))
+                if 'hide-value' in metadata:
+                    return True
+
+        return False
+
+    def add_directive_header(self, sig: str) -> None:
+        super().add_directive_header(sig)
+        sourcename = self.get_sourcename()
+        if self.options.annotation is SUPPRESS or self.should_suppress_directive_header():
+            pass
+        elif self.options.annotation:
+            self.add_line('   :annotation: %s' % self.options.annotation, sourcename)
+        else:
+            if self.config.autodoc_typehints != 'none':
+                # obtain type annotation for this attribute
+                annotations = get_type_hints(self.parent, None,
+                                             self.config.autodoc_type_aliases)
+                if self.objpath[-1] in annotations:
+                    if self.config.autodoc_typehints_format == "short":
+                        objrepr = stringify_annotation(annotations.get(self.objpath[-1]),
+                                                       "smart")
+                    else:
+                        objrepr = stringify_annotation(annotations.get(self.objpath[-1]),
+                                                       "fully-qualified-except-typing")
+                    self.add_line('   :type: ' + objrepr, sourcename)
+
+            try:
+                if (self.options.no_value or self.should_suppress_value_header() or
+                        ismock(self.object)):
+                    pass
+                else:
+                    objrepr = object_description(self.object)
+                    self.add_line('   :value: ' + objrepr, sourcename)
+            except ValueError:
+                pass
+
+    def get_attribute_comment(self, parent: Any, attrname: str) -> list[str] | None:
+        for cls in inspect.getmro(parent):
+            try:
+                module = safe_getattr(cls, '__module__')
+                qualname = safe_getattr(cls, '__qualname__')
+
+                analyzer = ModuleAnalyzer.for_module(module)
+                analyzer.analyze()
+                if qualname and self.objpath:
+                    key = (qualname, attrname)
+                    if key in analyzer.attr_docs:
+                        return list(analyzer.attr_docs[key])
+            except (AttributeError, PycodeError):
+                pass
+
+        return None
+
+    def get_doc(self) -> list[list[str]] | None:
+        # Check the attribute has a docstring-comment
+        comment = self.get_attribute_comment(self.parent, self.objpath[-1])
+        if comment:
+            return [comment]
+
+        try:
+            # Disable `autodoc_inherit_docstring` temporarily to avoid to obtain
+            # a docstring from the value which descriptor returns unexpectedly.
+            # ref: https://github.com/sphinx-doc/sphinx/issues/7805
+            orig = self.config.autodoc_inherit_docstrings
+            self.config.autodoc_inherit_docstrings = False  # type: ignore
+            return super().get_doc()
+        finally:
+            self.config.autodoc_inherit_docstrings = orig  # type: ignore
+
+    def add_content(self, more_content: StringList | None) -> None:
+        # Disable analyzing attribute comment on Documenter.add_content() to control it on
+        # AttributeDocumenter.add_content()
+        self.analyzer = None
+
+        if more_content is None:
+            more_content = StringList()
+        self.update_content(more_content)
+        super().add_content(more_content)
+
+
+class PropertyDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter):  # type: ignore
+    """
+    Specialized Documenter subclass for properties.
+    """
+    objtype = 'property'
+    member_order = 60
+
+    # before AttributeDocumenter
+    priority = AttributeDocumenter.priority + 1
+
+    @classmethod
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
+                            ) -> bool:
+        if isinstance(parent, ClassDocumenter):
+            if inspect.isproperty(member):
+                return True
+            else:
+                __dict__ = safe_getattr(parent.object, '__dict__', {})
+                obj = __dict__.get(membername)
+                return isinstance(obj, classmethod) and inspect.isproperty(obj.__func__)
+        else:
+            return False
+
+    def import_object(self, raiseerror: bool = False) -> bool:
+        """Check the exisitence of uninitialized instance attribute when failed to import
+        the attribute."""
+        ret = super().import_object(raiseerror)
+        if ret and not inspect.isproperty(self.object):
+            __dict__ = safe_getattr(self.parent, '__dict__', {})
+            obj = __dict__.get(self.objpath[-1])
+            if isinstance(obj, classmethod) and inspect.isproperty(obj.__func__):
+                self.object = obj.__func__
+                self.isclassmethod = True
+                return True
+            else:
+                return False
+
+        self.isclassmethod = False
+        return ret
+
+    def document_members(self, all_members: bool = False) -> None:
+        pass
+
+    def get_real_modname(self) -> str:
+        real_modname = self.get_attr(self.parent or self.object, '__module__', None)
+        return real_modname or self.modname
+
+    def add_directive_header(self, sig: str) -> None:
+        super().add_directive_header(sig)
+        sourcename = self.get_sourcename()
+        if inspect.isabstractmethod(self.object):
+            self.add_line('   :abstractmethod:', sourcename)
+        if self.isclassmethod:
+            self.add_line('   :classmethod:', sourcename)
+
+        if safe_getattr(self.object, 'fget', None):  # property
+            func = self.object.fget
+        elif safe_getattr(self.object, 'func', None):  # cached_property
+            func = self.object.func
+        else:
+            func = None
+
+        if func and self.config.autodoc_typehints != 'none':
+            try:
+                signature = inspect.signature(func,
+                                              type_aliases=self.config.autodoc_type_aliases)
+                if signature.return_annotation is not Parameter.empty:
+                    if self.config.autodoc_typehints_format == "short":
+                        objrepr = stringify_annotation(signature.return_annotation, "smart")
+                    else:
+                        objrepr = stringify_annotation(signature.return_annotation,
+                                                       "fully-qualified-except-typing")
+                    self.add_line('   :type: ' + objrepr, sourcename)
+            except TypeError as exc:
+                logger.warning(__("Failed to get a function signature for %s: %s"),
+                               self.fullname, exc)
+                return None
+            except ValueError:
+                return None
+
+
+def autodoc_attrgetter(app: Sphinx, obj: Any, name: str, *defargs: Any) -> Any:
+    """Alternative getattr() for types"""
+    for typ, func in app.registry.autodoc_attrgettrs.items():
+        if isinstance(obj, typ):
+            return func(obj, name, *defargs)
+
+    return safe_getattr(obj, name, *defargs)
+
+
+def setup(app: Sphinx) -> dict[str, Any]:
+    app.add_autodocumenter(ModuleDocumenter)
+    app.add_autodocumenter(ClassDocumenter)
+    app.add_autodocumenter(ExceptionDocumenter)
+    app.add_autodocumenter(DataDocumenter)
+    app.add_autodocumenter(FunctionDocumenter)
+    app.add_autodocumenter(DecoratorDocumenter)
+    app.add_autodocumenter(MethodDocumenter)
+    app.add_autodocumenter(AttributeDocumenter)
+    app.add_autodocumenter(PropertyDocumenter)
+
+    app.add_config_value('autoclass_content', 'class', True, ENUM('both', 'class', 'init'))
+    app.add_config_value('autodoc_member_order', 'alphabetical', True,
+                         ENUM('alphabetical', 'bysource', 'groupwise'))
+    app.add_config_value('autodoc_class_signature', 'mixed', True, ENUM('mixed', 'separated'))
+    app.add_config_value('autodoc_default_options', {}, True)
+    app.add_config_value('autodoc_docstring_signature', True, True)
+    app.add_config_value('autodoc_mock_imports', [], True)
+    app.add_config_value('autodoc_typehints', "signature", True,
+                         ENUM("signature", "description", "none", "both"))
+    app.add_config_value('autodoc_typehints_description_target', 'all', True,
+                         ENUM('all', 'documented', 'documented_params'))
+    app.add_config_value('autodoc_type_aliases', {}, True)
+    app.add_config_value('autodoc_typehints_format', "short", 'env',
+                         ENUM("fully-qualified", "short"))
+    app.add_config_value('autodoc_warningiserror', True, True)
+    app.add_config_value('autodoc_inherit_docstrings', True, True)
+    app.add_event('autodoc-before-process-signature')
+    app.add_event('autodoc-process-docstring')
+    app.add_event('autodoc-process-signature')
+    app.add_event('autodoc-skip-member')
+    app.add_event('autodoc-process-bases')
+
+    app.setup_extension('sphinx.ext.autodoc.preserve_defaults')
+    app.setup_extension('sphinx.ext.autodoc.type_comment')
+    app.setup_extension('sphinx.ext.autodoc.typehints')
+
+    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}