Merge pull request #8991 from tk0miya/typing_OptionSpec

refactor: Add a type alias for the option_spec of directives; OptionSpec

8 files changed, 39 insertions, 33 deletions

diff --git a/sphinx/domains/c.py b/sphinx/domains/c.py
index 0c5f41ba1..ed02701d4 100644
--- a/sphinx/domains/c.py
+++ b/sphinx/domains/c.py
@@ -39,6 +39,7 @@ from sphinx.util.cfamily import (ASTAttribute, ASTBaseBase, ASTBaseParenExprList
 from sphinx.util.docfields import Field, TypedField
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.nodes import make_refnode
+from sphinx.util.typing import OptionSpec
 
 logger = logging.getLogger(__name__)
 T = TypeVar('T')
@@ -3104,7 +3105,7 @@ class CObject(ObjectDescription[ASTDeclaration]):
               names=('rtype',)),
     ]
 
-    option_spec = {
+    option_spec: OptionSpec = {
         'noindexentry': directives.flag,
     }
 
@@ -3344,7 +3345,7 @@ class CNamespaceObject(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec = {}  # type: Dict
+    option_spec: OptionSpec = {}
 
     def run(self) -> List[Node]:
         rootSymbol = self.env.domaindata['c']['root_symbol']
@@ -3374,7 +3375,7 @@ class CNamespacePushObject(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec = {}  # type: Dict
+    option_spec: OptionSpec = {}
 
     def run(self) -> List[Node]:
         if self.arguments[0].strip() in ('NULL', '0', 'nullptr'):
@@ -3405,7 +3406,7 @@ class CNamespacePopObject(SphinxDirective):
     required_arguments = 0
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec = {}  # type: Dict
+    option_spec: OptionSpec = {}
 
     def run(self) -> List[Node]:
         stack = self.env.temp_data.get('c:namespace_stack', None)
@@ -3559,10 +3560,10 @@ class AliasTransform(SphinxTransform):
 
 
 class CAliasObject(ObjectDescription):
-    option_spec = {
+    option_spec: OptionSpec = {
         'maxdepth': directives.nonnegative_int,
         'noroot': directives.flag,
-    }  # type: Dict
+    }
 
     def run(self) -> List[Node]:
         """
diff --git a/sphinx/domains/changeset.py b/sphinx/domains/changeset.py
index 33234d6e0..23a3375ce 100644
--- a/sphinx/domains/changeset.py
+++ b/sphinx/domains/changeset.py
@@ -17,6 +17,7 @@ from sphinx import addnodes
 from sphinx.domains import Domain
 from sphinx.locale import _
 from sphinx.util.docutils import SphinxDirective
+from sphinx.util.typing import OptionSpec
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
@@ -53,7 +54,7 @@ class VersionChange(SphinxDirective):
     required_arguments = 1
     optional_arguments = 1
     final_argument_whitespace = True
-    option_spec = {}  # type: Dict
+    option_spec: OptionSpec = {}
 
     def run(self) -> List[Node]:
         node = addnodes.versionmodified()
diff --git a/sphinx/domains/cpp.py b/sphinx/domains/cpp.py
index 52b9ad23c..b9ba1f559 100644
--- a/sphinx/domains/cpp.py
+++ b/sphinx/domains/cpp.py
@@ -39,6 +39,7 @@ from sphinx.util.cfamily import (ASTAttribute, ASTBaseBase, ASTBaseParenExprList
 from sphinx.util.docfields import Field, GroupedField
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.nodes import make_refnode
+from sphinx.util.typing import OptionSpec
 
 logger = logging.getLogger(__name__)
 T = TypeVar('T')
@@ -6718,7 +6719,7 @@ class CPPObject(ObjectDescription[ASTDeclaration]):
               names=('returns', 'return')),
     ]
 
-    option_spec = {
+    option_spec: OptionSpec = {
         'noindexentry': directives.flag,
         'tparam-line-spec': directives.flag,
     }
@@ -6984,7 +6985,7 @@ class CPPNamespaceObject(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec = {}  # type: Dict
+    option_spec: OptionSpec = {}
 
     def run(self) -> List[Node]:
         rootSymbol = self.env.domaindata['cpp']['root_symbol']
@@ -7015,7 +7016,7 @@ class CPPNamespacePushObject(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec = {}  # type: Dict
+    option_spec: OptionSpec = {}
 
     def run(self) -> List[Node]:
         if self.arguments[0].strip() in ('NULL', '0', 'nullptr'):
@@ -7047,7 +7048,7 @@ class CPPNamespacePopObject(SphinxDirective):
     required_arguments = 0
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec = {}  # type: Dict
+    option_spec: OptionSpec = {}
 
     def run(self) -> List[Node]:
         stack = self.env.temp_data.get('cpp:namespace_stack', None)
@@ -7224,10 +7225,10 @@ class AliasTransform(SphinxTransform):
 
 
 class CPPAliasObject(ObjectDescription):
-    option_spec = {
+    option_spec: OptionSpec = {
         'maxdepth': directives.nonnegative_int,
         'noroot': directives.flag,
-    }  # type: Dict
+    }
 
     def run(self) -> List[Node]:
         """
diff --git a/sphinx/domains/index.py b/sphinx/domains/index.py
index fd1a76613..9ecfae439 100644
--- a/sphinx/domains/index.py
+++ b/sphinx/domains/index.py
@@ -20,6 +20,7 @@ from sphinx.environment import BuildEnvironment
 from sphinx.util import logging, split_index_msg
 from sphinx.util.docutils import ReferenceRole, SphinxDirective
 from sphinx.util.nodes import process_index_entry
+from sphinx.util.typing import OptionSpec
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
@@ -67,7 +68,7 @@ class IndexDirective(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec = {
+    option_spec: OptionSpec = {
         'name': directives.unchanged,
     }
 
diff --git a/sphinx/domains/javascript.py b/sphinx/domains/javascript.py
index f612fb914..b34cff509 100644
--- a/sphinx/domains/javascript.py
+++ b/sphinx/domains/javascript.py
@@ -28,6 +28,7 @@ from sphinx.util import logging
 from sphinx.util.docfields import Field, GroupedField, TypedField
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.nodes import make_id, make_refnode
+from sphinx.util.typing import OptionSpec
 
 logger = logging.getLogger(__name__)
 
@@ -47,7 +48,7 @@ class JSObject(ObjectDescription[Tuple[str, str]]):
     #: based on directive nesting
     allow_nesting = False
 
-    option_spec = {
+    option_spec: OptionSpec = {
         'noindex': directives.flag,
         'noindexentry': directives.flag,
     }
@@ -253,7 +254,7 @@ class JSModule(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = False
-    option_spec = {
+    option_spec: OptionSpec = {
         'noindex': directives.flag
     }
 
diff --git a/sphinx/domains/python.py b/sphinx/domains/python.py
index cd701ca15..ace7cedf4 100644
--- a/sphinx/domains/python.py
+++ b/sphinx/domains/python.py
@@ -38,7 +38,7 @@ from sphinx.util.docfields import Field, GroupedField, TypedField
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.inspect import signature_from_str
 from sphinx.util.nodes import find_pending_xref_condition, make_id, make_refnode
-from sphinx.util.typing import TextlikeNode
+from sphinx.util.typing import OptionSpec, TextlikeNode
 
 logger = logging.getLogger(__name__)
 
@@ -357,7 +357,7 @@ class PyObject(ObjectDescription[Tuple[str, str]]):
     :cvar allow_nesting: Class is an object that allows for nested namespaces
     :vartype allow_nesting: bool
     """
-    option_spec = {
+    option_spec: OptionSpec = {
         'noindex': directives.flag,
         'noindexentry': directives.flag,
         'module': directives.unchanged,
@@ -575,7 +575,7 @@ class PyObject(ObjectDescription[Tuple[str, str]]):
 class PyFunction(PyObject):
     """Description of a function."""
 
-    option_spec = PyObject.option_spec.copy()
+    option_spec: OptionSpec = PyObject.option_spec.copy()
     option_spec.update({
         'async': directives.flag,
     })
@@ -629,7 +629,7 @@ class PyDecoratorFunction(PyFunction):
 class PyVariable(PyObject):
     """Description of a variable."""
 
-    option_spec = PyObject.option_spec.copy()
+    option_spec: OptionSpec = PyObject.option_spec.copy()
     option_spec.update({
         'type': directives.unchanged,
         'value': directives.unchanged,
@@ -662,7 +662,7 @@ class PyClasslike(PyObject):
     Description of a class-like object (classes, interfaces, exceptions).
     """
 
-    option_spec = PyObject.option_spec.copy()
+    option_spec: OptionSpec = PyObject.option_spec.copy()
     option_spec.update({
         'final': directives.flag,
     })
@@ -689,7 +689,7 @@ class PyClasslike(PyObject):
 class PyMethod(PyObject):
     """Description of a method."""
 
-    option_spec = PyObject.option_spec.copy()
+    option_spec: OptionSpec = PyObject.option_spec.copy()
     option_spec.update({
         'abstractmethod': directives.flag,
         'async': directives.flag,
@@ -750,7 +750,7 @@ class PyMethod(PyObject):
 class PyClassMethod(PyMethod):
     """Description of a classmethod."""
 
-    option_spec = PyObject.option_spec.copy()
+    option_spec: OptionSpec = PyObject.option_spec.copy()
 
     def run(self) -> List[Node]:
         self.name = 'py:method'
@@ -762,7 +762,7 @@ class PyClassMethod(PyMethod):
 class PyStaticMethod(PyMethod):
     """Description of a staticmethod."""
 
-    option_spec = PyObject.option_spec.copy()
+    option_spec: OptionSpec = PyObject.option_spec.copy()
 
     def run(self) -> List[Node]:
         self.name = 'py:method'
@@ -790,7 +790,7 @@ class PyDecoratorMethod(PyMethod):
 class PyAttribute(PyObject):
     """Description of an attribute."""
 
-    option_spec = PyObject.option_spec.copy()
+    option_spec: OptionSpec = PyObject.option_spec.copy()
     option_spec.update({
         'type': directives.unchanged,
         'value': directives.unchanged,
@@ -897,7 +897,7 @@ class PyModule(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = False
-    option_spec = {
+    option_spec: OptionSpec = {
         'platform': lambda x: x,
         'synopsis': lambda x: x,
         'noindex': directives.flag,
@@ -961,7 +961,7 @@ class PyCurrentModule(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = False
-    option_spec = {}  # type: Dict
+    option_spec: OptionSpec = {}
 
     def run(self) -> List[Node]:
         modname = self.arguments[0].strip()
diff --git a/sphinx/domains/rst.py b/sphinx/domains/rst.py
index 07bf46b75..6b4f1c0ff 100644
--- a/sphinx/domains/rst.py
+++ b/sphinx/domains/rst.py
@@ -25,6 +25,7 @@ from sphinx.locale import _, __
 from sphinx.roles import XRefRole
 from sphinx.util import logging
 from sphinx.util.nodes import make_id, make_refnode
+from sphinx.util.typing import OptionSpec
 
 logger = logging.getLogger(__name__)
 
@@ -117,7 +118,7 @@ class ReSTDirectiveOption(ReSTMarkup):
     """
     Description of an option for reST directive.
     """
-    option_spec = ReSTMarkup.option_spec.copy()
+    option_spec: OptionSpec = ReSTMarkup.option_spec.copy()
     option_spec.update({
         'type': directives.unchanged,
     })
diff --git a/sphinx/domains/std.py b/sphinx/domains/std.py
index 8b10c8547..274c29c87 100644
--- a/sphinx/domains/std.py
+++ b/sphinx/domains/std.py
@@ -30,7 +30,7 @@ from sphinx.roles import XRefRole
 from sphinx.util import docname_join, logging, ws_re
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.nodes import clean_astext, make_id, make_refnode
-from sphinx.util.typing import RoleFunction
+from sphinx.util.typing import OptionSpec, RoleFunction
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
@@ -132,7 +132,7 @@ class Target(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec = {}  # type: Dict
+    option_spec: OptionSpec = {}
 
     def run(self) -> List[Node]:
         # normalize whitespace in fullname like XRefRole does
@@ -265,7 +265,7 @@ class Program(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec = {}  # type: Dict
+    option_spec: OptionSpec = {}
 
     def run(self) -> List[Node]:
         program = ws_re.sub('-', self.arguments[0].strip())
@@ -329,7 +329,7 @@ class Glossary(SphinxDirective):
     required_arguments = 0
     optional_arguments = 0
     final_argument_whitespace = False
-    option_spec = {
+    option_spec: OptionSpec = {
         'sorted': directives.flag,
     }
 
@@ -482,7 +482,7 @@ class ProductionList(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec = {}  # type: Dict
+    option_spec: OptionSpec = {}
 
     def run(self) -> List[Node]:
         domain = cast(StandardDomain, self.env.get_domain('std'))