X Tutup
Skip to content

DOC: Fix doc builds with Sphinx 9 #31020

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
timhoffm merged 3 commits into from
Jan 24, 2026
Merged

DOC: Fix doc builds with Sphinx 9 #31020

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cc62eba
Remove mutable defaults from tool manager functions
QuLogic Jan 23, 2026
6663149
DOC: Use the old class-based autodoc with Sphinx 9
QuLogic Jan 23, 2026
cde8c89
DOC: Fix cross-references to new _Buttons class
QuLogic Jan 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions doc/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -899,3 +899,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
18 changes: 12 additions & 6 deletions lib/matplotlib/backend_tools.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -934,6 +934,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,
Expand All @@ -953,12 +954,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`.

Expand All @@ -968,14 +970,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):
Copy link
Copy Markdown
Member

@timhoffm timhoffm Jan 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This subtly changes semantics. Now it is possible to do

from matplotlib import backend_tools
backend_tools = {...}

and affect the used default. Before it was still possible to modify the default by in-place modification, but I haven't found any such usage on github.

Overall, I believe this is not intended to be configurable. Should we make it private? Or alternatively switch to DEFAULT_TOOLS if you want to reference the values in the documentation.

Copy link
Copy Markdown
Member Author

@QuLogic QuLogic Jan 24, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, fair point, it is a bit more flexible, but someone could already do that if they wanted to as the default value is a reference:

>>> foo = ['a', 'b', 'c']
>>> def bar(baz=foo):
...     print(baz)
...     
>>> bar()
['a', 'b', 'c']
>>> foo.append('d')  # Modify the global in-place.
>>> bar()
['a', 'b', 'c', 'd']  # Reflects the modification.

Copy link
Copy Markdown
Member

@timhoffm timhoffm Jan 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's what I'be been referring to as "in-place" modification. But doesn't seem to be used in the wild.

Copy link
Copy Markdown
Member Author

@QuLogic QuLogic Jan 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah sorry, I missed that. Well, I don't have any great need to document these. The main goal is removing them from the signature so Sphinx doesn't try to link the classes erroneously, and I've only linked them because previously you could see what the default was (if in a bit difficult to read manner.) If we don't necessarily want to document what the default is, then we can remove the docs for these, and possibly deprecate the variables.

Copy link
Copy Markdown
Member

@timhoffm timhoffm Jan 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've merged as is to unbreak the doc builds now.

The differences in handling tool defaults are relatively low-impact. Any variant is good enough for now. I'll think about the proper solution and made a tracking issue for that: #31027

"""
Add multiple tools to the container.

Expand All @@ -987,9 +991,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)
6 changes: 3 additions & 3 deletions lib/matplotlib/backend_tools.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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: ...
4 changes: 2 additions & 2 deletions lib/matplotlib/widgets.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1152,7 +1152,7 @@ class CheckButtons(_Buttons):
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
----------
Expand Down Expand Up @@ -1652,7 +1652,7 @@ class RadioButtons(_Buttons):
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
----------
Expand Down
Loading
X Tutup