👌 Make ExtensionMetadata type public and use it in internal extensions (sphinx-doc#12153)

This type alias has now been fully documented for public consumption.

This will be beneficial to the sphinx ecosystem,
to aide/encourage extension developers to provide the correct metadata.

Co-authored-by: Bénédikt Tran <[email protected]>

Author: chrisjsewell

CHANGES.rst

@@ -22,6 +22,11 @@ Deprecated
 Features added
 --------------
 
+* Add public type alias :class:`sphinx.util.typing.ExtensionMetadata`.
+  This can be used by extension developers
+  to annotate the return type of their ``setup`` function.
+  Patch by Chris Sewell.
+
 * #12133: Allow ``external`` roles to reference object types
   (rather than role names). Patch by Chris Sewell.
 

doc/development/tutorials/examples/helloworld.py

@@ -1,14 +1,17 @@
 from docutils import nodes
 from docutils.parsers.rst import Directive
 
+from sphinx.application import Sphinx
+from sphinx.util.typing import ExtensionMetadata
+
 
 class HelloWorld(Directive):
     def run(self):
         paragraph_node = nodes.paragraph(text='Hello World!')
         return [paragraph_node]
 
 
-def setup(app):
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_directive('helloworld', HelloWorld)
 
     return {

doc/development/tutorials/examples/recipe.py

@@ -3,10 +3,12 @@
 from docutils.parsers.rst import directives
 
 from sphinx import addnodes
+from sphinx.application import Sphinx
 from sphinx.directives import ObjectDescription
 from sphinx.domains import Domain, Index
 from sphinx.roles import XRefRole
 from sphinx.util.nodes import make_refnode
+from sphinx.util.typing import ExtensionMetadata
 
 
 class RecipeDirective(ObjectDescription):
@@ -153,7 +155,7 @@ def add_recipe(self, signature, ingredients):
         self.data['recipes'].append((name, signature, 'Recipe', self.env.docname, anchor, 0))
 
 
-def setup(app):
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_domain(RecipeDomain)
 
     return {

doc/development/tutorials/examples/todo.py

@@ -1,8 +1,10 @@
 from docutils import nodes
 from docutils.parsers.rst import Directive
 
+from sphinx.application import Sphinx
 from sphinx.locale import _
 from sphinx.util.docutils import SphinxDirective
+from sphinx.util.typing import ExtensionMetadata
 
 
 class todo(nodes.Admonition, nodes.Element):
@@ -111,7 +113,7 @@ def process_todo_nodes(app, doctree, fromdocname):
         node.replace_self(content)
 
 
-def setup(app):
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_config_value('todo_include_todos', False, 'html')
 
     app.add_node(todolist)

doc/extdev/utils.rst

@@ -35,3 +35,9 @@ Utility components
 
 .. autoclass:: sphinx.events.EventManager
    :members:
+
+Utility types
+-------------
+
+.. autoclass:: sphinx.util.typing.ExtensionMetadata
+   :members:

sphinx/addnodes.py

@@ -12,6 +12,7 @@
     from docutils.nodes import Element
 
     from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
 
 # deprecated name -> (object to return, canonical path or empty string)
 _DEPRECATED_OBJECTS = {
@@ -573,7 +574,7 @@ class manpage(nodes.Inline, nodes.FixedTextElement):
     """Node for references to manpages."""
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_node(toctree)
 
     app.add_node(desc)

sphinx/builders/changes.py

@@ -18,6 +18,7 @@
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
 
 logger = logging.getLogger(__name__)
 
@@ -155,7 +156,7 @@ def finish(self) -> None:
         pass
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_builder(ChangesBuilder)
 
     return {

sphinx/builders/dirhtml.py

@@ -3,14 +3,15 @@
 from __future__ import annotations
 
 from os import path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from sphinx.builders.html import StandaloneHTMLBuilder
 from sphinx.util import logging
 from sphinx.util.osutil import SEP, os_path
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
 
 logger = logging.getLogger(__name__)
 
@@ -42,7 +43,7 @@ def get_outfilename(self, pagename: str) -> str:
         return outfilename
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.setup_extension('sphinx.builders.html')
 
     app.add_builder(DirectoryHTMLBuilder)

sphinx/builders/dummy.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from sphinx.builders import Builder
 from sphinx.locale import __
@@ -11,6 +11,7 @@
     from docutils.nodes import Node
 
     from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
 
 
 class DummyBuilder(Builder):
@@ -38,7 +39,7 @@ def finish(self) -> None:
         pass
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_builder(DummyBuilder)
 
     return {

sphinx/builders/epub3.py

@@ -22,6 +22,7 @@
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
 
 logger = logging.getLogger(__name__)
 
@@ -257,7 +258,7 @@ def convert_epub_css_files(app: Sphinx, config: Config) -> None:
     config.epub_css_files = epub_css_files  # type: ignore[attr-defined]
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_builder(Epub3Builder)
 
     # config values