Backport PR #31020: DOC: Fix doc builds with Sphinx 9

timhoffm · meeseeksmachine · commit 2da812c08373 · 2026-04-17T19:38:13.000Z
diff --git a/doc/conf.py b/doc/conf.py
@@ -891,3 +891,4 @@ def setup(app):
     if sphinx.version_info[:2] < (7, 1):
         app.connect('html-page-context', add_html_cache_busting, priority=1000)
     generate_ScalarMappable_docs()
+    app.config.autodoc_use_legacy_class_based = True
diff --git a/lib/matplotlib/backend_tools.py b/lib/matplotlib/backend_tools.py
@@ -937,6 +937,7 @@ def trigger(self, *args, **kwargs):
         self.toolmanager.message_event(message, self)
 
 
+#: The default tools to add to a tool manager.
 default_tools = {'home': ToolHome, 'back': ToolBack, 'forward': ToolForward,
                  'zoom': ToolZoom, 'pan': ToolPan,
                  'subplots': ConfigureSubplotsBase,
@@ -956,12 +957,13 @@ def trigger(self, *args, **kwargs):
                  'copy': ToolCopyToClipboardBase,
                  }
 
+#: The default tools to add to a container.
 default_toolbar_tools = [['navigation', ['home', 'back', 'forward']],
                          ['zoompan', ['pan', 'zoom', 'subplots']],
                          ['io', ['save', 'help']]]
 
 
-def add_tools_to_manager(toolmanager, tools=default_tools):
+def add_tools_to_manager(toolmanager, tools=None):
     """
     Add multiple tools to a `.ToolManager`.
 
@@ -971,14 +973,16 @@ def add_tools_to_manager(toolmanager, tools=default_tools):
         Manager to which the tools are added.
     tools : {str: class_like}, optional
         The tools to add in a {name: tool} dict, see
-        `.backend_managers.ToolManager.add_tool` for more info.
+        `.backend_managers.ToolManager.add_tool` for more info. If not specified, then
+        defaults to `.default_tools`.
     """
-
+    if tools is None:
+        tools = default_tools
     for name, tool in tools.items():
         toolmanager.add_tool(name, tool)
 
 
-def add_tools_to_container(container, tools=default_toolbar_tools):
+def add_tools_to_container(container, tools=None):
     """
     Add multiple tools to the container.
 
@@ -990,9 +994,11 @@ def add_tools_to_container(container, tools=default_toolbar_tools):
     tools : list, optional
         List in the form ``[[group1, [tool1, tool2 ...]], [group2, [...]]]``
         where the tools ``[tool1, tool2, ...]`` will display in group1.
-        See `.backend_bases.ToolContainerBase.add_tool` for details.
+        See `.backend_bases.ToolContainerBase.add_tool` for details. If not specified,
+        then defaults to `.default_toolbar_tools`.
     """
-
+    if tools is None:
+        tools = default_toolbar_tools
     for group, grouptools in tools:
         for position, tool in enumerate(grouptools):
             container.add_tool(tool, group, position)
diff --git a/lib/matplotlib/backend_tools.pyi b/lib/matplotlib/backend_tools.pyi
@@ -112,10 +112,10 @@ class ToolHelpBase(ToolBase):
 
 class ToolCopyToClipboardBase(ToolBase): ...
 
-default_tools: dict[str, ToolBase]
+default_tools: dict[str, type[ToolBase]]
 default_toolbar_tools: list[list[str | list[str]]]
 
 def add_tools_to_manager(
-    toolmanager: ToolManager, tools: dict[str, type[ToolBase]] = ...
+    toolmanager: ToolManager, tools: dict[str, type[ToolBase]] | None = ...
 ) -> None: ...
-def add_tools_to_container(container: ToolContainerBase, tools: list[Any] = ...) -> None: ...
+def add_tools_to_container(container: ToolContainerBase, tools: list[Any] | None = ...) -> None: ...
diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py
@@ -980,7 +980,7 @@ class CheckButtons(AxesWidget):
     For the check buttons to remain responsive you must keep a
     reference to this object.
 
-    Connect to the CheckButtons with the `.on_clicked` method.
+    Connect to the CheckButtons with the `~._Buttons.on_clicked` method.
 
     Attributes
     ----------
@@ -1545,7 +1545,7 @@ class RadioButtons(AxesWidget):
     For the buttons to remain responsive you must keep a reference to this
     object.
 
-    Connect to the RadioButtons with the `.on_clicked` method.
+    Connect to the RadioButtons with the `~._Buttons.on_clicked` method.
 
     Attributes
     ----------
