Skip to content

add subplots to axes documentation #11454

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
Jun 21, 2018
Merged

add subplots to axes documentation #11454

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
18 changes: 15 additions & 3 deletions doc/api/axes_api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,30 @@
================
``Axes`` class
================
====
axes
====

.. currentmodule:: matplotlib.axes

.. autoclass:: Axes
:no-members:
:no-undoc-members:
:show-inheritance:

.. contents:: Table of Contents
:depth: 2
:local:
:backlinks: entry
:class: multicol-toc

Subplots
Copy link
Member

@jklymak jklymak Jun 18, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

This appears in the TOC as a level above "Plotting", so I think needs a lower decoration level:

https://10464-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/api/axes_api.html

Copy link
Contributor Author

@fredrik-1 fredrik-1 Jun 18, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

I tried to change the header hierarchy without checking the result... and I see now that didn't work and that I didn't know how headers works in rst. I tried to lower the subplot level and that level stayed the same but everything else toggled its level... Tries again.

edit: I thought I pushed a new version yesterday but something went wrong. It should be updated now.

Copy link
Member

@timhoffm timhoffm Jun 18, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

I don't think this is going the right way. This whole page was documenting the Axes class. You've now changed it to the axes module and inserted the subplots stuff in between the class description and the list of functions (the sections here are used to group the Axes methods by topic).

It may be ok to document the complete axes module here, but then one would have to change the structure. The TOC is currently "within the class" and only listing its functions.

It would have to go to the top and be restructured to something like:

  • Axes
    • Plotting
    • ...
  • Subplots

Copy link
Contributor Author

Choose a reason for hiding this comment

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

But why should there be a special page for documenting the Axes class instead of the axes module?

But the page can of course be restructured in same way.

Copy link
Member

Choose a reason for hiding this comment

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

The Axes class is so large and fundamental, that it might have a dedicated page. But I'm not saying it has to be that way. I also laid out a possible structure if the file should contain the whole module.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I am not sure what is the best. Your structure is of course a possibility (it was not in your post when I wrote my answer).

I am thinking that axes is one module, it consist of 2 public classes and a factory function. Most axes used in practice are also subplots. The suggest structure show the 2 classes and the factory function at the beginning in a way that don't take up to much place and I doubt that the order is confusing.

What about changing the name to subplot sub module or something like that?

One problem is that the axes module is not included in the module list in neither version of the documents.

========

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

SubplotBase
subplot_class_factory

Plotting
========
Expand Down
3 changes: 2 additions & 1 deletion doc/api/figure_api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ Classes
.. autosummary::
:toctree: _as_gen/
:template: autosummary.rst
:nosignatures:

AxesStack
Figure
Expand All @@ -29,6 +30,6 @@ Functions
.. autosummary::
:toctree: _as_gen/
:template: autosummary.rst
:nosignatures:

figaspect

12 changes: 7 additions & 5 deletions lib/matplotlib/axes/_subplots.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,11 +187,13 @@ def _make_twin_axes(self, *kl, **kwargs):

@functools.lru_cache(None)
def subplot_class_factory(axes_class=None):
# This makes a new class that inherits from SubplotBase and the
# given axes_class (which is assumed to be a subclass of Axes).
# This is perhaps a little bit roundabout to make a new class on
# the fly like this, but it means that a new Subplot class does
# not have to be created for every type of Axes.
"""
This makes a new class that inherits from `.SubplotBase` and the
given axes_class (which is assumed to be a subclass of `.axes.Axes`).
This is perhaps a little bit roundabout to make a new class on
the fly like this, but it means that a new Subplot class does
not have to be created for every type of Axes.
"""
if axes_class is None:
axes_class = Axes
return type("%sSubplot" % axes_class.__name__,
Expand Down