Consolidate option spec processing into _directive_options.py (#14009)

Author: AA-Turner

doc/conf.py

@@ -235,6 +235,7 @@
     ('py:class', 'pygments.lexer.Lexer'),
     ('py:class', 'sphinx.directives.ObjDescT'),
     ('py:class', 'sphinx.domains.IndexEntry'),
+    # sphinx.application.Sphinx.add_autodocumenter
     ('py:class', 'sphinx.ext.autodoc.Documenter'),
     ('py:class', 'sphinx.errors.NoUri'),
     ('py:class', 'sphinx.roles.XRefRole'),

sphinx/application.py

@@ -1629,8 +1629,9 @@ def add_autodocumenter(self, cls: type[Documenter], override: bool = False) -> N
         logger.debug('[app] adding autodocumenter: %r', cls)
         from sphinx.ext.autodoc.directive import AutodocDirective
 
-        self.registry.add_documenter(cls.objtype, cls)
-        self.add_directive('auto' + cls.objtype, AutodocDirective, override=override)
+        objtype = cls.objtype  # type: ignore[attr-defined]
+        self.registry.add_documenter(objtype, cls)
+        self.add_directive('auto' + objtype, AutodocDirective, override=override)
 
     def add_autodoc_attrgetter(
         self, typ: type, getter: Callable[[Any, str, Any], Any]

sphinx/ext/autodoc/__init__.py

@@ -23,19 +23,6 @@
     members_option,
     merge_members_option,
 )
-from sphinx.ext.autodoc._documenters import (
-    AttributeDocumenter,
-    ClassDocumenter,
-    DataDocumenter,
-    DecoratorDocumenter,
-    Documenter,
-    ExceptionDocumenter,
-    FunctionDocumenter,
-    MethodDocumenter,
-    ModuleDocumenter,
-    PropertyDocumenter,
-    TypeAliasDocumenter,
-)
 from sphinx.ext.autodoc._event_listeners import between, cut_lines
 from sphinx.ext.autodoc._member_finder import ObjectMember, special_member_re
 from sphinx.ext.autodoc._sentinels import ALL, EMPTY, SUPPRESS, UNINITIALIZED_ATTR
@@ -45,26 +32,18 @@
 from sphinx.ext.autodoc._sentinels import (
     SLOTS_ATTR as SLOTSATTR,
 )
+from sphinx.ext.autodoc.directive import AutodocDirective
 from sphinx.ext.autodoc.importer import py_ext_sig_re
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
+    from sphinx.ext.autodoc._property_types import _AutodocObjType
     from sphinx.util.typing import ExtensionMetadata
 
 __all__ = (
     # Useful event listener factories for autodoc-process-docstring
     'cut_lines',
     'between',
-    # Documenters
-    'AttributeDocumenter',
-    'ClassDocumenter',
-    'DataDocumenter',
-    'DecoratorDocumenter',
-    'ExceptionDocumenter',
-    'FunctionDocumenter',
-    'MethodDocumenter',
-    'ModuleDocumenter',
-    'PropertyDocumenter',
     # This class is only used in ``sphinx.ext.autodoc.directive``,
     # but we export it here for compatibility.
     # See: https://github.com/sphinx-doc/sphinx/issues/4538
@@ -93,21 +72,25 @@
     'ObjectMember',
     'py_ext_sig_re',
     'special_member_re',
-    'Documenter',
 )
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:
-    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_autodocumenter(TypeAliasDocumenter)
+    obj_type: _AutodocObjType
+    for obj_type in (
+        'module',
+        'class',
+        'exception',
+        'function',
+        'decorator',
+        'method',
+        'property',
+        'attribute',
+        'data',
+        'type',
+    ):
+        # register the automodule, autoclass, etc. directives
+        app.add_directive(f'auto{obj_type}', AutodocDirective)
 
     app.add_config_value(
         'autoclass_content',

sphinx/ext/autodoc/_directive_options.py

@@ -9,8 +9,9 @@
 
 if TYPE_CHECKING:
     from collections.abc import Mapping, Set
-    from typing import Any, Literal, Self
+    from typing import Any, Final, Literal, Self
 
+    from sphinx.ext.autodoc._property_types import _AutodocObjType
     from sphinx.ext.autodoc._sentinels import ALL_T, EMPTY_T, SUPPRESS_T
     from sphinx.util.typing import OptionSpec
 
@@ -184,13 +185,67 @@ def __getattr__(self, name: str) -> Any:
             return None
 
 
+_OPTION_SPEC_COMMON: Final[OptionSpec] = {
+    'no-index': bool_option,
+    'no-index-entry': bool_option,
+}
+_OPTION_SPEC_HAS_MEMBERS: Final[OptionSpec] = _OPTION_SPEC_COMMON | {
+    'members': members_option,
+    'exclude-members': exclude_members_option,
+    'undoc-members': bool_option,
+    'private-members': members_option,
+    'special-members': members_option,
+    'member-order': member_order_option,
+    'show-inheritance': bool_option,
+}
+_OPTION_SPEC_MODULE_SPECIFIC: Final[OptionSpec] = {
+    'ignore-module-all': bool_option,
+    'imported-members': bool_option,
+    'deprecated': bool_option,
+    'platform': identity,
+    'synopsis': identity,
+}
+_OPTION_SPEC_CLASS_SPECIFIC: Final[OptionSpec] = {
+    'class-doc-from': class_doc_from_option,
+    'inherited-members': inherited_members_option,
+}
+_OPTION_SPEC_ASSIGNMENT: Final[OptionSpec] = _OPTION_SPEC_COMMON | {
+    'annotation': annotation_option,
+    'no-value': bool_option,
+}
+_OPTION_SPEC_DEPRECATED: Final[OptionSpec] = {
+    'noindex': bool_option,
+}
+_OPTION_SPEC_FUNCTION_DEF: Final = _OPTION_SPEC_COMMON | _OPTION_SPEC_DEPRECATED
+_OPTION_SPECS: Final[Mapping[_AutodocObjType, OptionSpec]] = {
+    'module': _OPTION_SPEC_HAS_MEMBERS
+    | _OPTION_SPEC_MODULE_SPECIFIC
+    | {'inherited-members': inherited_members_option}  # special case
+    | _OPTION_SPEC_DEPRECATED,
+    'class': _OPTION_SPEC_HAS_MEMBERS
+    | _OPTION_SPEC_CLASS_SPECIFIC
+    | _OPTION_SPEC_DEPRECATED,
+    'exception': _OPTION_SPEC_HAS_MEMBERS
+    | _OPTION_SPEC_CLASS_SPECIFIC
+    | _OPTION_SPEC_DEPRECATED,
+    'function': _OPTION_SPEC_FUNCTION_DEF,
+    'decorator': _OPTION_SPEC_FUNCTION_DEF,
+    'method': _OPTION_SPEC_FUNCTION_DEF,
+    'property': _OPTION_SPEC_FUNCTION_DEF,
+    'attribute': _OPTION_SPEC_ASSIGNMENT | _OPTION_SPEC_DEPRECATED,
+    'data': _OPTION_SPEC_ASSIGNMENT | _OPTION_SPEC_DEPRECATED,
+    'type': _OPTION_SPEC_ASSIGNMENT,
+}
+
+
 def _process_documenter_options(
     *,
-    option_spec: OptionSpec,
+    obj_type: _AutodocObjType,
     default_options: dict[str, str | bool],
     options: dict[str, str | None],
-) -> dict[str, object]:
-    """Recognize options of Documenter from user input."""
+) -> _AutoDocumenterOptions:
+    """Recognize options of object type from user input."""
+    option_spec = _OPTION_SPECS[obj_type]
     for name in AUTODOC_DEFAULT_OPTIONS:
         if name not in option_spec:
             continue
@@ -210,4 +265,5 @@ def _process_documenter_options(
             # remove '+' from option argument if there's nothing to merge it with
             options[name] = opt_value.removeprefix('+')
 
-    return assemble_option_dict(options.items(), option_spec)  # type: ignore[arg-type]
+    opts = assemble_option_dict(options.items(), option_spec)  # type: ignore[arg-type]
+    return _AutoDocumenterOptions.from_directive_options(opts)

sphinx/ext/autodoc/_docstrings.py

@@ -297,7 +297,7 @@ def _get_doc(
 
     if props.obj_type not in {'module', 'data'} and _new_docstrings is not None:
         # docstring already returned previously, then modified due to
-        # ``Documenter._find_signature()``. Just return the
+        # ``_extract_signatures_from_docstring()``. Just return the
         # previously-computed result, so that we don't lose the processing.
         return _new_docstrings
 

sphinx/ext/autodoc/_documenters.py

@@ -1,31 +1,5 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
-
-from sphinx.ext.autodoc._directive_options import (
-    annotation_option,
-    bool_option,
-    class_doc_from_option,
-    exclude_members_option,
-    identity,
-    inherited_members_option,
-    member_order_option,
-    members_option,
-)
-
-if TYPE_CHECKING:
-    from typing import ClassVar
-
-    from sphinx.ext.autodoc._property_types import (
-        _AssignStatementProperties,
-        _ClassDefProperties,
-        _FunctionDefProperties,
-        _ItemProperties,
-        _ModuleProperties,
-        _TypeStatementProperties,
-    )
-    from sphinx.util.typing import OptionSpec
-
 
 class Documenter:
     """A Documenter knows how to autodocument a single object type.  When
@@ -41,144 +15,3 @@ class Documenter:
     in fact, it will be used to parse an auto directive's options that matches
     the Documenter.
     """
-
-    props: _ItemProperties
-
-    #: name by which the directive is called (auto...) and the default
-    #: generated directive name
-    objtype: ClassVar = 'object'
-    #: true if the generated content may contain titles
-    titles_allowed: ClassVar = True
-
-    option_spec: ClassVar[OptionSpec] = {
-        'no-index': bool_option,
-        'no-index-entry': bool_option,
-        'noindex': bool_option,
-    }
-
-
-class ModuleDocumenter(Documenter):
-    """Specialized Documenter subclass for modules."""
-
-    props: _ModuleProperties
-
-    objtype = 'module'
-
-    option_spec: ClassVar[OptionSpec] = {
-        'members': members_option,
-        'undoc-members': bool_option,
-        'no-index': bool_option,
-        'no-index-entry': 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,
-        'noindex': bool_option,
-    }
-
-
-class FunctionDocumenter(Documenter):
-    """Specialized Documenter subclass for functions."""
-
-    props: _FunctionDefProperties
-
-    objtype = 'function'
-
-
-class DecoratorDocumenter(FunctionDocumenter):
-    """Specialized Documenter subclass for decorator functions."""
-
-    props: _FunctionDefProperties
-
-    objtype = 'decorator'
-
-
-class ClassDocumenter(Documenter):
-    """Specialized Documenter subclass for classes."""
-
-    props: _ClassDefProperties
-
-    objtype = 'class'
-    option_spec: ClassVar[OptionSpec] = {
-        'members': members_option,
-        'undoc-members': bool_option,
-        'no-index': bool_option,
-        'no-index-entry': 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,
-        'noindex': bool_option,
-    }
-
-
-class ExceptionDocumenter(ClassDocumenter):
-    """Specialized ClassDocumenter subclass for exceptions."""
-
-    props: _ClassDefProperties
-
-    objtype = 'exception'
-
-
-class DataDocumenter(Documenter):
-    """Specialized Documenter subclass for data items."""
-
-    props: _AssignStatementProperties
-
-    objtype = 'data'
-    option_spec: ClassVar[OptionSpec] = dict(Documenter.option_spec)
-    option_spec['annotation'] = annotation_option
-    option_spec['no-value'] = bool_option
-
-
-class MethodDocumenter(Documenter):
-    """Specialized Documenter subclass for methods (normal, static and class)."""
-
-    props: _FunctionDefProperties
-
-    objtype = 'method'
-    directivetype = 'method'
-
-
-class AttributeDocumenter(Documenter):
-    """Specialized Documenter subclass for attributes."""
-
-    props: _AssignStatementProperties
-
-    objtype = 'attribute'
-    option_spec: ClassVar[OptionSpec] = dict(Documenter.option_spec)
-    option_spec['annotation'] = annotation_option
-    option_spec['no-value'] = bool_option
-
-
-class PropertyDocumenter(Documenter):
-    """Specialized Documenter subclass for properties."""
-
-    props: _FunctionDefProperties
-
-    objtype = 'property'
-
-
-class TypeAliasDocumenter(Documenter):
-    """Specialized Documenter subclass for type aliases."""
-
-    props: _TypeStatementProperties
-
-    objtype = 'type'
-    option_spec: ClassVar[OptionSpec] = {
-        'no-index': bool_option,
-        'no-index-entry': bool_option,
-        'annotation': annotation_option,
-        'no-value': bool_option,
-    }

sphinx/ext/autodoc/_member_finder.py

@@ -52,7 +52,7 @@
 class ObjectMember:
     """A member of object.
 
-    This is used for the result of `Documenter.get_module_members()` to
+    This is used for the result of `_get_members_to_document()` to
     represent each member of the object.
     """
 
@@ -152,7 +152,7 @@ def _gather_members(
     # document non-skipped members
     member_documenters: list[tuple[_ItemProperties, bool, str]] = []
     for member_name, member, is_attr in filtered_members:
-        # prefer the documenter with the highest priority
+        # prefer the object type with the highest priority
         obj_type = _best_object_type_for_member(
             member=member,
             member_name=member_name,