Preview:

I think @ksunden's scipy tutorial was in this vein, so he might have some thing.

ETA- I also kinda prefer the unstyled flowchart.

Meta concern here- I'm not sure somebody who doesn't already know what we mean by simple vs complex grid (for example) will be able to follow this chart, so I think it kinda needs little thumbnails/visual cues in the decision diamonds.

I'm not sure somebody who doesn't already know what we mean by simple vs complex grid

I've changed to "regular grid" and "general grid".

I've changed to "regular grid" and "general grid".

I'm not sure that's any better?

since this chart can be made in matplotlib with connection patch, let me try to make what I'm thinking of?

https://matplotlib.org/devdocs/users/explain/axes/axes_intro.html#creating-axes

How does this relate to the above? At the least they should be cross linked if not merged.

Your link is the first point of contact for creating Axes, right after explaining the elements of a figure. It should not go into much all the creation details. IMHO it should only contain subplots() and mention that there are more methods.

OTOH the diagram is meant as a comprehensive list of all Axes creation methods together with a compact guide which ones are for which purpose.

I'm not sure that's any better?

since this chart can be made in matplotlib with connection patch, let me try to make what I'm thinking of?

"regular" is for sure better than "simple" as it is more specific. "general" and "complex" are rather equally bad, but I cannot come up with a short defining term for "unequally spaced grid and/or including spans over multiple grid cells".

but I cannot come up with a short defining term for "unequally spaced grid and/or including spans over multiple grid cells".

irregular or unstructured - that's the language we use in plot types?

Also yes I misspoke - regular is way better than simple for describing the grid, but I think visual cues would be better still so I'm drafting up that figure

Folks, thanks for the feedback. As mentioned above, I'm not going to bikeshed this (sorry, but I really don't have the time). I wanted to get this in, because #17376 has 4 upvotes (my most-upvoted issue and among the top 25 of upvotes on any issue). IMHO this already an improvement as is. Anybody can pick up from here and refine.

My wish would be that we keep the aspects that I tried to incorporate into this diagram:

• Provide a comprehensive list of all Axes creation methods
• Distinguish and show parallels between pyplot and the object methods
• De-emphasize less used variants (i.e. gridspecs and subplot)
• Give a recipe which method to use based on the desired Axes properties/type

I think having all of them is essential to being able to drill down to one preferred solution for a use case. It doesn't help if we give multiple solutions without further distinctions or guidance: This example part of the original plot is quite unhelpful and rather scary

Bonus points when rendering this as SVG with links to the methods.

irregular or unstructured - that's the language we use in plot types?

Not really. There's still partial structure/regularity. - For data points (in plot types) that means really random positions. We're not that random here.

We also have https://matplotlib.org/devdocs/users/explain/axes/arranging_axes.html. Can you add this there? I dont think this needs a separate page that overlaps both sections so completely.

Working out the most messy version of this that I deeply dislike, I think this might be most useful as a table or flow chart on
https://matplotlib.org/devdocs/users/explain/axes/index.html to direct folks to which tutorial they should read? Especially since it mixes inset and twin in?

really ugly draft of table

wanted to get this in, because #17376 has 4 upvotes

This urgency ties into the meta issue I'm having w/ how docs are handled in this project, which is that all this new content is great and popular in the individual but turns into an inconsistent undiscoverable blob in the aggregate. Like taking this very awesome chart and trying to situate it and now I'm thinking it really shouldn't be a chart that implies these things are somehow mutually exclusive since any axes can have an inset or a twin.

@story645 thanks for pointing out the visual aspect of this with your example. I came from the "recipe" idea to ask a series of questions and by that guide people to the appropriate function. However, with the visualization we can just show the layouts and people can immediately see what they get and pick one.

I believe this is best done as a pictographic representation, rather than trying to plot it with matplotlib. We can well create SVGs (e.g. with Inkscape) and embed them. As a quick example, we could go in this direction:

meta issue I'm having w/ how docs are handled in this project, which is that all this new content is great and popular in the individual but turns into an inconsistent undiscoverable blob in the aggregate.

I fundamentally agree. We need more fundamental restructuring and consolidation. This essentially belongs to https://matplotlib.org/devdocs/users/explain/axes/arranging_axes.html but doesn't fit into its current narrative. I'm a big fan of doing things stepwise. First put all the cards on the table, and then rearange them - even at the risk at having temporarily more clutter. As we see above, there are still conceptual discussions on this idea itself. Tying this to a restructuring of https://matplotlib.org/devdocs/users/explain/axes/arranging_axes.html is too much and almost guaranteed to stall (at least with our current processes).

It hardly seems a heavy lift to add it at the beginning of arranging_axes. Even just as-is, if you don't want to edit any existing material. I think that's preferable to a new top TOC entry.

I believe this is best done as a pictographic representation,

I like your pictograph and I think stripping out the ticks is the right move . I was thinking sphinx design table/grid mostly cause then all the auto reflow goodness and the code markup/intersphinx.

Tying this to a restructuring of https://matplotlib.org/devdocs/users/explain/axes/arranging_axes.html is too much and almost guaranteed to stall

I hear, and @jklymak has made similar points about other PRs and I don't think either of you are wrong - but I'm also concerned about making a restructure harder every time we add new cards. I don't think that's what's going on here exactly, but I think we should have a discussion/consensus on a shared direction that we can then use to guide PR reviews.

ETA:

However, with the visualization we can just show the layouts and people can immediately see what they get and pick one.

ain't that the best part about being a visualization library? ;)

I'll reiterate the above. I don't see anything here that is incompatible with the narrative in arranging_axes. It's missing some things that are in arranging_axes, and arranging_axes is missing some things here (twins and insets) but the info is largely the same. Having a visual overview with links to the appropriate subsections and or methods seems like a great idea.

From a meta point of view, I agree that we should have some consensus about scope and audience. I'd encourage us to schedule a call or two in the fall for this. However you can't codify taste, and at some point people are just going to do things differently. What I feel we should avoid is lots of back and forth about taste issues. In the case of disagreement, @tacaswell will have to decide, or delegate someone to make intermediate decisions.

However you can't codify taste, and at some point people are just going to do things differently.

One the one hand don't want to pull this discussion further OT, but fundamentally disagree this is a taste issue - it's about consistency in expository writing so that the docs are cohesive and coherent. Tim and Anthony are responsible for this on the API side, I don't think it's unreasonable to want the same on the docs side.

Precisely because observations like this

It's missing some things that are in arranging_axes, and arranging_axes is missing some things here (twins and insets)

are much easier to make if, going back to the card metaphor, all the cards are expected to come from the same deck.

ETA: while yes I have my preferred approaches - chunking, scaffolding - that I'm gonna advocate for, I'm right now more interested in us agreeing on some small handful. Partially also b/c I think approach is largely what distinguishes user guide from tutorial from gallery - for example, the plot types gallery is our cleanest section of the docs, and is also the one w/ the clearest guidelines on what belongs.

We have two proposed format for this graphic, and four proposed locations. I don't feel there is an objective criteria to be applied to say one is more "consistent" or "coherent". There are only suggestions and arguments, and eventually a subjective decision will have to be made.

I don't feel there is an objective criteria to be applied to say one is more "consistent" or "coherent".

The flow chart approach has coherency issues because it implies all these methods are at the same level and are mutually exclusive 'cause they're part of the same decision tree. This is why it's not sitting cleanly in arranging_axes which l agree with you is generally speaking the right place for most of this table. While I proposed putting it on the landing page for this section, I now think it's not comprehensive enough for that.

ETA: Pictures are a value add, yes, but I also think one of the reasons for review is to offer suggestions that would improve the contribution.

Just found this little bit in the cheatsheets https://matplotlib.org/cheatsheets/cheatsheets.pdf

Just found this little bit in the cheatsheets

👍 looks like mine but they should switch to subplot_mosaic. :)

Small nit: GridSpec.subplots() really makes a complete grid, though one can use subplots() on a subgridspec when constructing complex layouts.