Skip to content

DOC: mark mosaic as no longer provisional #24891

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.

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 4 commits into from
Jan 7, 2023

Conversation

tacaswell
Copy link
Member

PR Summary

Mark mosaic as no longer provisional.

I also moved this from tutorials -> examples as this is much a how-to and "gallery" is what we have that matches the divio "how-to" best.

@tacaswell tacaswell added this to the v3.7.0 milestone Jan 5, 2023
@tacaswell tacaswell marked this pull request as ready for review January 5, 2023 23:08
Co-authored-by: Jody Klymak <jklymak@gmail.com>
Copy link
Member

@jklymak jklymak left a comment

Choose a reason for hiding this comment

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

If you search for "mosaic" on the rendered docs example page, you do not get this example showing up. I think folks wanting a quick guide as to how subplot_mosaic works will want that in the title.

Copy link
Member

@oscargus oscargus left a comment

Choose a reason for hiding this comment

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

Should there be some sort of release note for this? It may make sense for users to know that this has happened in another way than noting that the provisional note has been removed.

@oscargus
Copy link
Member

oscargus commented Jan 6, 2023

I may argue that it is indeed a tutorial type of document here. One could possibly add an example or two, but considering the style and length of the documentation, it seems more like a tutorial than an example. But if others disagree, I will not block based on this.

@rcomer
Copy link
Member

rcomer commented Jan 6, 2023

it seems more like a tutorial than an example

Within the tutorials, I prefer the subject categories (Colors, Text) to the basic/intermediate/advanced categories. The subject links help me navigate to the thing that I currently want to learn about, whereas I don't know the difficulty level of the thing until I've learned it. I wonder if we could make a "layouts" tutorial category for mosaic, constrained layout, tight layout and "arranging multiple Axes in a Figure". I appreciate that that is a little out of scope for this PR though.

@tacaswell
Copy link
Member Author

If we use the terminology from https://documentation.divio.com/tutorials/ then this is not a tutorial because it is just N related examples all on one page. To riff on their cooking analogy, this is a list of every way to cook and egg not instructions on how to make a nice omelette breakfast. Under this rubric I think many of the things currently in tutorials are miss-categorized (https://matplotlib.org/stable/tutorials/introductory/lifecycle.html and maybe the image one may be the only ones that actually fit the divio definition).

Good point about the release notes, I'll add that.

@jklymak
Copy link
Member

jklymak commented Jan 6, 2023

Certainly some of what we have in "tutorials" are not actual tutorials, but are long-form documentation of features and how the library works. I'd argue that 10 or 12 examples as part of a narrative of how a feature works is not really an "Example" either.

Let's open a new issue to discuss how to organize the tutorials, since this has come up a few times. Personally I wouldn't move the subplots_mosaic to Examples, but don't feel strongly about it.

EDIT: See #24900 for further discussion of "tutorials"....

@tacaswell tacaswell force-pushed the doc_mosaic_not_provisional branch from a27fa2b to 0bc10e9 Compare January 7, 2023 02:50
@ksunden ksunden merged commit b06433c into matplotlib:main Jan 7, 2023
@tacaswell tacaswell deleted the doc_mosaic_not_provisional branch January 7, 2023 11:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants