Thanks to visit codestin.com
Credit goes to github.com

Skip to content

DOC: organize figure API #26629

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
merged 1 commit into from
Sep 15, 2023
Merged

DOC: organize figure API #26629

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
303 changes: 301 additions & 2 deletions doc/api/figure_api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,5 +5,304 @@
.. currentmodule:: matplotlib.figure

.. automodule:: matplotlib.figure
:members:
:inherited-members:
:no-members:
:no-undoc-members:

The Figure class
================
.. autosummary::
:toctree: _as_gen
:template: autosummary_class_only.rst
:nosignatures:

Figure
Comment on lines +11 to +18
Copy link
Member

Choose a reason for hiding this comment

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

A downside of this - and I just realized that we already have the issue for Axes - that all code links `.Figure` go to the sub-page, whereas logically it would make more sense to have them point to the index page.

I have no idea how to improve on this with existing means (well, one could introduce a custom directive :c:`Figure` , but (i) I'm reluctant to give up on the simpler formatting of `.Figure` and (ii) since that is a non-standard appoach, it's likely that new standard refrences `.Figure` will keep creeping in.) I've opened an issue to sphinx. Maybe we have to live with that for now.

Copy link
Member Author

Choose a reason for hiding this comment

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

I see what you are saying, but I'm not convinced it is a huge problem:

`matplotlib.figure` is the right way to get the overall index if that is what we want in the docs.

`.Figure` takes us to the instantiation docs, which I think we do not want in the overview.

At least on non-mobile, the left-hand navigation and the breadcrumb is pretty clear where the module level description is:

fig

An alternative may be that we make entries for matplotlib.figure.Figure and matplotlib.figure.SubFigure. We don't do this with any other APIs currently, but I don't think there is any reason they API reference has to slavishly correspond to files in the library directory. I think this would mean figure_Figure_api.rst and figure_SubFigure_api.rst, but that doesn't seem the end of the world.

Finally, an even more radical suggestions would be to rearrange the source code itself; eg have a subfigure module, and split FigureBase into its own private module. That doesn't seem the end of the world - I doubt many people are doing import matplotlib.figure.SubFigure yet.

So, I think the proposed change here is better than what we currently have, but I'm open to relatively major surgery if we can get something even better.

Copy link
Member Author

Choose a reason for hiding this comment

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

Thinking about this more though: even if we do the more radical suggestions above, I don't see how we get the init docs onto their own page and out of the intro.

Your suggestion to sphinx seems reasonable. Not sure how we emulate that internally.

Copy link
Member

@timhoffm timhoffm Sep 1, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

One could try to separate class and init docstring, put the class on the overview page and init in subpage where the class currently is. May be possible through appropriate configuration https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration.

But that can be a follow up PR. I suggest to merge this as is for now.

Copy link
Member Author

Choose a reason for hiding this comment

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

I think a fair bit is possible with templates as well.

Copy link
Member Author

Choose a reason for hiding this comment

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

See newest version...



Adding Axes and SubFigures
==========================

.. autosummary::
:toctree: _as_gen
:template: autosummary.rst
:nosignatures:

Figure.add_axes
Figure.add_subplot
Figure.subplots
Figure.subplot_mosaic
Figure.add_gridspec
Figure.get_axes
Figure.axes
Figure.delaxes
Figure.subfigures
Figure.add_subfigure

Saving
======

.. autosummary::
:toctree: _as_gen
:template: autosummary.rst
:nosignatures:

Figure.savefig


Annotating
==========

.. autosummary::
:toctree: _as_gen
:template: autosummary.rst
:nosignatures:

Figure.colorbar
Figure.legend
Figure.text
Figure.suptitle
Figure.get_suptitle
Figure.supxlabel
Figure.get_supxlabel
Figure.supylabel
Figure.get_supylabel
Figure.align_labels
Figure.align_xlabels
Figure.align_ylabels
Figure.autofmt_xdate


Figure geometry
===============

.. autosummary::
:toctree: _as_gen
:template: autosummary.rst
:nosignatures:

Figure.set_size_inches
Figure.get_size_inches
Figure.set_figheight
Figure.get_figheight
Figure.set_figwidth
Figure.get_figwidth
Figure.dpi
Figure.set_dpi
Figure.set_dpi

Subplot layout
==============

.. autosummary::
:toctree: _as_gen
:template: autosummary.rst
:nosignatures:

Figure.subplots_adjust
Figure.set_layout_engine
Figure.get_layout_engine

Discouraged or deprecated
-------------------------

.. autosummary::
:toctree: _as_gen
:template: autosummary.rst
:nosignatures:

Figure.tight_layout
Figure.set_tight_layout
Figure.get_tight_layout
Figure.set_constrained_layout
Figure.get_constrained_layout
Figure.set_constrained_layout_pads
Figure.get_constrained_layout_pads

Interactive
===========

.. seealso::

- :ref:`event-handling`

.. autosummary::
:toctree: _as_gen
:template: autosummary.rst
:nosignatures:

Figure.ginput
Figure.add_axobserver
Figure.waitforbuttonpress
Figure.pick

Modifying appearance
====================

.. autosummary::
:toctree: _as_gen
:template: autosummary.rst
:nosignatures:

Figure.set_frameon
Figure.get_frameon
Figure.set_linewidth
Figure.get_linewidth
Figure.set_facecolor
Figure.get_facecolor
Figure.set_edgecolor
Figure.get_edgecolor

Adding and getting Artists
==========================

.. autosummary::
:toctree: _as_gen
:template: autosummary.rst
:nosignatures:

Figure.add_artist
Figure.get_children
Figure.figimage

Getting and modifying state
===========================

.. seealso::

- :ref:`interactive_figures`

.. autosummary::
:toctree: _as_gen
:template: autosummary.rst
:nosignatures:

Figure.clear
Figure.gca
Figure.sca
Figure.get_tightbbox
Figure.get_window_extent
Figure.show
Figure.set_canvas
Figure.draw
Figure.draw_without_rendering
Figure.draw_artist

.. _figure-api-subfigure:

SubFigure
=========

Matplotlib has the concept of a `~.SubFigure`, which is a logical figure inside
a parent `~.Figure`. It has many of the same methods as the parent. See
:ref:`nested_axes_layouts`.

.. plot::

fig = plt.figure(layout='constrained', figsize=(4, 2.5), facecolor='lightgoldenrodyellow')
Copy link
Member

Choose a reason for hiding this comment

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

This is probably the silliest little nit but I wish this figure was a bit wider to match the text width.

Copy link
Member Author

Choose a reason for hiding this comment

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

The width of the figure is fixed at approximately 1/2 the maximum width of the text, so it would have to be twice as wide to match the text width. You must be looking at a thinner viewport.
layout


# Make two subfigures, left ones more narrow than right ones:
sfigs = fig.subfigures(1, 2, width_ratios=[0.8, 1])
sfigs[0].set_facecolor('khaki')
sfigs[1].set_facecolor('lightsalmon')

# Add subplots to left subfigure:
lax = sfigs[0].subplots(2, 1)
sfigs[0].suptitle('Left subfigure')

# Add subplots to right subfigure:
rax = sfigs[1].subplots(1, 2)
sfigs[1].suptitle('Right subfigure')

# suptitle for the main figure:
fig.suptitle('Figure')

SubFigure class
---------------

.. autosummary::
:toctree: _as_gen
:template: autosummary_class_only.rst
:nosignatures:

SubFigure

Adding Axes and SubFigures
--------------------------
.. autosummary::
:toctree: _as_gen
:template: autosummary.rst
:nosignatures:

SubFigure.add_axes
SubFigure.add_subplot
SubFigure.subplots
SubFigure.subplot_mosaic
SubFigure.add_gridspec
SubFigure.delaxes
SubFigure.add_subfigure
SubFigure.subfigures

Annotating
----------

.. autosummary::
:toctree: _as_gen
:template: autosummary.rst
:nosignatures:

SubFigure.colorbar
SubFigure.legend
SubFigure.text
SubFigure.suptitle
SubFigure.get_suptitle
SubFigure.supxlabel
SubFigure.get_supxlabel
SubFigure.supylabel
SubFigure.get_supylabel
SubFigure.align_labels
SubFigure.align_xlabels
SubFigure.align_ylabels

Adding and getting Artists
--------------------------

.. autosummary::
:toctree: _as_gen
:template: autosummary.rst
:nosignatures:

SubFigure.add_artist
SubFigure.get_children

Modifying appearance
--------------------

.. autosummary::
:toctree: _as_gen
:template: autosummary.rst
:nosignatures:

SubFigure.set_frameon
SubFigure.get_frameon
SubFigure.set_linewidth
SubFigure.get_linewidth
SubFigure.set_facecolor
SubFigure.get_facecolor
SubFigure.set_edgecolor
SubFigure.get_edgecolor

Passthroughs
------------

.. autosummary::
:toctree: _as_gen
:template: autosummary.rst
:nosignatures:

SubFigure.set_dpi
SubFigure.get_dpi


FigureBase parent class
=======================

.. autoclass:: FigureBase
2 changes: 1 addition & 1 deletion doc/api/prev_api_changes/api_changes_3.4.2.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Behaviour changes
Rename first argument to ``subplot_mosaic``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Both `.FigureBase.subplot_mosaic`, and `.pyplot.subplot_mosaic` have had the
Both `.Figure.subplot_mosaic`, and `.pyplot.subplot_mosaic` have had the
first position argument renamed from *layout* to *mosaic*. This is because we
are considering to consolidate *constrained_layout* and *tight_layout* keyword
arguments in the Figure creation functions of `.pyplot` into a single *layout*
Expand Down
2 changes: 1 addition & 1 deletion doc/api/prev_api_changes/api_changes_3.5.0/behaviour.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Behaviour changes
First argument to ``subplot_mosaic`` renamed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Both `.FigureBase.subplot_mosaic`, and `.pyplot.subplot_mosaic` have had the
Both `.Figure.subplot_mosaic`, and `.pyplot.subplot_mosaic` have had the
first positional argument renamed from *layout* to *mosaic*. As we have
consolidated the *constrained_layout* and *tight_layout* keyword arguments in
the Figure creation functions of `.pyplot` into a single *layout* keyword
Expand Down
4 changes: 2 additions & 2 deletions doc/users/prev_whats_new/whats_new_3.4.0.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -634,8 +634,8 @@ supxlabel and supylabel
-----------------------

It is possible to add x- and y-labels to a whole figure, analogous to
`.FigureBase.suptitle` using the new `.FigureBase.supxlabel` and
`.FigureBase.supylabel` methods.
`.Figure.suptitle` using the new `.Figure.supxlabel` and
`.Figure.supylabel` methods.

.. plot::

Expand Down
10 changes: 5 additions & 5 deletions galleries/examples/subplots_axes_and_figures/figure_title.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,10 @@

Each axes can have a title (or actually three - one each with *loc* "left",
"center", and "right"), but is sometimes desirable to give a whole figure
(or `.SubFigure`) an overall title, using `.FigureBase.suptitle`.
(or `.SubFigure`) an overall title, using `.Figure.suptitle`.

We can also add figure-level x- and y-labels using `.FigureBase.supxlabel` and
`.FigureBase.supylabel`.
We can also add figure-level x- and y-labels using `.Figure.supxlabel` and
`.Figure.supylabel`.
"""

import matplotlib.pyplot as plt
Expand All @@ -31,8 +31,8 @@
fig.suptitle('Different types of oscillations', fontsize=16)

# %%
# A global x- or y-label can be set using the `.FigureBase.supxlabel` and
# `.FigureBase.supylabel` methods.
# A global x- or y-label can be set using the `.Figure.supxlabel` and
# `.Figure.supylabel` methods.


with get_sample_data('Stocks.csv') as file:
Expand Down
2 changes: 1 addition & 1 deletion galleries/examples/subplots_axes_and_figures/gridspec_nested.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
set the position for a nested grid of subplots.

Note that the same functionality can be achieved more directly with
`~.FigureBase.subfigures`; see
`~.Figure.subfigures`; see
:doc:`/gallery/subplots_axes_and_figures/subfigures`.

"""
Expand Down
2 changes: 2 additions & 0 deletions galleries/users_explain/axes/arranging_axes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -228,6 +228,8 @@ def annotate_axes(ax, text, fontsize=18):
fig.suptitle('plt.subplot_mosaic()')

# %%
# .. _nested_axes_layouts:
#
# Nested Axes layouts
# -------------------
#
Expand Down
Loading