DOC: user/explain reorg (and moving a lot of tutorials). #25395

jklymak · 2023-03-05T18:21:56Z

PR Summary

This is a big documentation re-organization. It addresses the problem that the tutorials have much of what should really be part of a Users Guide, but are not organized as a Guide, and are lacking some narrative glue to bring them together. The over-all idea here is to basically make /users/explain a sphinx-gallery based Using Matplotlib Guide.

Overview

Most of what is in galleries/tutorials has been moved to galleries/users_explain, which gets served at /users/explain in the docs, replacing the material that was formerly there. /users/explain now has the following sections:

Quick start guide
Figures
Axes (or Subplots)
Using Artists
Customizing Matplotlib with style sheets and rcParams
Controlling and labelling Axis objects
Colors
Text
Animations using Matplotlib
Toolkits

Some of these were directly copied over from tutorials, others we re-organized some. For instance there is a new axes/index.rst that tries to explain Axes.

Much of the "Advanced" and some of the "Intermediate" material was put in a table of contents. eg. /galleries/users_explain/artists/index.rst has a general introduction to Artists, followed by:

.. toctree::
    :maxdepth: 1

    Concept: Automated color cycle <color_cycle>
    Concept: optimizing Artists for performance <performance>
    Concept: Paths <paths>
    Concept: Path effects guide <patheffects_guide>
    In Depth: understanding the extent keyword argument of imshow <imshow_extent>
    transforms_tutorial

I did almost no editing of any of the material. Some probably needs it after being moved, but getting it to the "right" spot is a start.

Redirects and refs:

Everything I moved, I used a redirect-from directive to keep book marks correct.
For anything I moved I changed :doc: references to :ref: references. That will make any further re-organization easier.

Plan forward

This is too big to review in whole. I think it would be most productive if folks would comment on the

a) the general structure
b) any suggestions for top-level sections and structure of users/explain
c) comment on any sub-pages that they feel are mis-placed

My hope would be to get the structure merged soonish so that we have the rest of the 3.8 cycle to continue to fix it. The little bit of new material should be reviewed/rewritten at that point, probably someone other than me, but I'll argue that it should be merged before it's perfect. The old material we should go through to improve and better integrate. We should also take PRs to fill in any gaps.

Where did things go?

Easiest to see where all the tutorials went at the new index page.

Actual new files:

galleries/tutorials/index.rst (instead of the old README.rst, so the TOC could be added).
galleries/users_explain/artists/index.rst
galleries/users_explain/axes/index.rst

Obvious Todos

Axis is not done
Make users_explain/index.rst look better
Much of the new prose needs to be followed up and cleaned.

melissawm · 2023-03-09T18:49:28Z

One comment is that it's not clear to me the difference between the tutorials under the user guide and the tutorials that live on the "Tutorials" top navbar. Could we just have all tutorials under the user guide, even if we have to keep two links to it if we don't want to remove the tutorials link from the navbar?

jklymak · 2023-03-09T19:10:41Z

One comment is that it's not clear to me the difference between the tutorials under the user guide and the tutorials that live on the "Tutorials" top navbar. Could we just have all tutorials under the user guide, even if we have to keep two links to it if we don't want to remove the tutorials link from the navbar?

Thats up for discussion. My idea was that Tutorials should be walk-throughs, which a couple of the current tutorials are. It may be possible to add more. Conversely most of the things I moved to User Guide were in-depth explanations of particular features. Some of the titles or text didn't change, but I think folks were bending the meaning of "tutorial" and then using that language (including a couple I wrote).

However, I'm open to removing Tutorials altogether, and/or moving some of the material I moved back to Tutorials. Depends on how robust we want that section to be.

melissawm · 2023-03-09T20:45:11Z

I see - in that case it sounds good, we should probably have a tracking issue or project listing all documents that should be reviewed for content once this is merged.

As far as making the ToC for users/explain look better - we could experiment with the https://sphinx-design.readthedocs.io/en/latest/index.html elements but I'm not sure we need this, maybe there are better/simpler ways. I tried something but not sure I like it tbh 😄

story645 · 2023-03-09T21:10:31Z

Even if we're leaving the gallery, can we still have little thumbnails next to each entry? I really don't want to lose the visual navigation, especially in tutorials where folks may not know what things are called.

tacaswell

I am delegating final authority on this PR to @jklymak to self-merge when he thinks it is ready.

I am pre-approving as well so GH will let him push the green button.

jklymak · 2023-03-09T21:24:01Z

Even if we're leaving the gallery, can we still have little thumbnails next to each entry? I really don't want to lose the visual navigation, especially in tutorials where folks may not know what things are called.

Just to be clear, the Examples/Gallery isn't going away, or at least I wouldn't be in favour of that.

I'm not sure most of the thumbnails for the Tutorial section are that useful? I'm totally in favour of adding visual elements to the index.rst files, but I don't think the sphinx-gallery README.txt->index.rst is flexible enough for what we need. OTOH, grabbing the thumbnails, which we know the location of, is a great strategy.

jklymak · 2023-03-09T21:40:54Z

As far as making the ToC for users/explain look better - we could experiment with the https://sphinx-design.readthedocs.io/en/latest/index.html

yes, I'm very much in favour of using sphinx-design; I just have made the most basic-looking TOC for now. I actually think making them look better is better dealt with in individual PRs (some of which I may submit) but they should get a full critique.

jklymak · 2023-03-11T01:02:02Z

Ping @timhoffm - I pinged you on gitter, but you may not be checking. Is the general idea of this re-org OK with you, with the understanding that details, improved aesthetics, and re-organizations can be done after it is submitted?

jklymak · 2023-03-17T01:24:34Z

If there are no general objections I'll merge this tomorrow. I'll also open some issues for individual pages I think need work or a second set of eyes, and folks should feel free to open issues as well.

jklymak · 2023-03-17T16:10:58Z

OK this was squash merged. Devs, please note that you need the main branch of sphinx-gallery to build the docs locally for a while.

timhoffm · 2023-03-17T16:12:14Z

galleries/tutorials/index.rst

+
+Many of our tutorials were moved from this section to :ref:`users-guide-explain`:
+
+Introductory


IMHO, we do not need to list the moved ones individually. There's a reason they are not in the tutorial section, anymore, so the top-level link given above should be enough. - May be ok to keep for a short transition period.

timhoffm · 2023-03-17T16:21:29Z

galleries/users_explain/index.rst

+
+.. redirect-from:: /users/explain
+
+Using Matplotlib


Before https://matplotlib.org/stable/users/explain/index.html titled "Explanations". Now this URL titles "Using Matplotlib", which is both confusing and changing the semantics.

Coming from

I categorize "Using matplotlib" in the top half "partical steps" (not very sure whether it's Tutorials or How-tos), whereas "Explanations" is in the lower part. While we can still move content around, we should get the organizational structure clear in this PR.

I think that graphic is a useful guide. OTOH I don't agree that any given document should be clearly in one section or another or that the top-level doc organization should strictly follow this. Imagine a textbook that only had theory in half the chapters, and worked examples in the other half. A tutorial with no basic "theory" isn't much use, similarly just discussing things in abstract is rarely a good way to learn.

What I have tried to do here is high-level Explanation of what an important part of the library is (say Axes), mixed with simple examples (mini Tutorials). Further Explanations (what we had in "Intermediate" and "Advanced") are then in the table of contents of that Section, and we should add more links to the examples (eg, Tutorials/How-to guides).

My argument would be that we never had the high-level explanations. Sometimes the API Reference had some explanation, and we had some getting-started tutorials, but we never explained what a Figure was or what an Axes was. Most of the so-called tutorials were really long Explanations that were easier to write in sphinx-gallery than rst. Some of the material in users/explain was pretty esoteric, other things were really fundamental.

So, I'm open to changing this organization, or changing the name "Using Matplotlib", but I think this is already substantially better than before, and can be filled out over the next few months to be really good.

timhoffm · 2023-03-17T16:24:41Z

Aaah, merged while commenting. 🐌 Ping @jklymak, please still have a look at my remarks.

jklymak · 2023-03-17T16:25:35Z

@timhoffm we can definitely change all of this based on comments or new issues. Note its not being back ported to 3.7.x so we have a few months to get it right

jklymak force-pushed the doc-user-reorg branch 11 times, most recently from 7b1bc33 to d5db532 Compare March 8, 2023 01:57

jklymak added status: needs comment/discussion needs consensus on next step Documentation: overhaul labels Mar 8, 2023

jklymak marked this pull request as ready for review March 8, 2023 02:42

github-actions bot added the status: needs rebase label Mar 8, 2023

jklymak force-pushed the doc-user-reorg branch from d5db532 to 1f67f6b Compare March 8, 2023 19:22

github-actions bot removed the status: needs rebase label Mar 8, 2023

jklymak force-pushed the doc-user-reorg branch 2 times, most recently from 4373b69 to 5f69e98 Compare March 8, 2023 20:27

jklymak mentioned this pull request Mar 8, 2023

DOC: start reorg explain #25218

Closed

6 tasks

tacaswell approved these changes Mar 9, 2023

View reviewed changes

github-actions bot added the status: needs rebase label Mar 12, 2023

DOC: make users/explain a sphinx gallery [ci doc]

49e6b9e

jklymak added 15 commits March 16, 2023 18:20

DOC: move fonts.rst to py file

e30f972

DOC: Move animations

92739dc

DOC: move backends

9626566

DOC: move performance [ci doc]

230fad3

DOC: fixes [ci doc]

3af6a59

DOC: Fix fonts [ci doc]

0a43f82

DOC: move autoscale

a1bcf87

DOC: move legend_guide

63bf0af

DOC: moved color_cycle tutorial

2b60692

DOC: fix flake8 [ci doc]

645d4b9

FIX

f24d067

Moved path and patheffects to artist [ci doc]

74b67f2

DOC: toolkits [ci doc]

0b687e1

DOC: move tutorials [ci doc]

fd60550

DOC: a bit more about ticks for axes

cb8e872

jklymak force-pushed the doc-user-reorg branch from ecd00a3 to cb8e872 Compare March 17, 2023 01:21

github-actions bot removed the status: needs rebase label Mar 17, 2023

rcomer mentioned this pull request Mar 17, 2023

Add an rc file setting for the pad parameter of tight_layout #5266

Closed

jklymak merged commit b5c141c into matplotlib:main Mar 17, 2023

jklymak deleted the doc-user-reorg branch March 17, 2023 16:13

jklymak mentioned this pull request Mar 17, 2023

DOC/BLD: stop using sg head [ci doc] #25487

Merged

6 tasks

timhoffm reviewed Mar 17, 2023

View reviewed changes

jklymak mentioned this pull request Mar 18, 2023

[Doc]: Axis explanation #25492

Open

QuLogic added this to the v3.8.0 milestone Mar 18, 2023

StefRe mentioned this pull request Mar 19, 2023

[Doc]: Thumbnail title in gallery show rst formatting characters #23884

Closed

jklymak mentioned this pull request Apr 4, 2023

DOC: fix Sphinx Gallery discussion to explain mixed subddirs #25618

Merged

6 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: user/explain reorg (and moving a lot of tutorials). #25395

DOC: user/explain reorg (and moving a lot of tutorials). #25395

jklymak commented Mar 5, 2023 •

edited

Loading

melissawm commented Mar 9, 2023

jklymak commented Mar 9, 2023

melissawm commented Mar 9, 2023

story645 commented Mar 9, 2023

tacaswell left a comment

jklymak commented Mar 9, 2023

jklymak commented Mar 9, 2023

jklymak commented Mar 11, 2023

jklymak commented Mar 17, 2023

jklymak commented Mar 17, 2023

timhoffm Mar 17, 2023

timhoffm Mar 17, 2023 •

edited

Loading

jklymak Mar 17, 2023

timhoffm commented Mar 17, 2023

jklymak commented Mar 17, 2023


		Many of our tutorials were moved from this section to :ref:`users-guide-explain`:

		Introductory

DOC: user/explain reorg (and moving a lot of tutorials). #25395

DOC: user/explain reorg (and moving a lot of tutorials). #25395

Conversation

jklymak commented Mar 5, 2023 • edited Loading

PR Summary

Overview

Redirects and refs:

Plan forward

Where did things go?

Obvious Todos

melissawm commented Mar 9, 2023

jklymak commented Mar 9, 2023

melissawm commented Mar 9, 2023

story645 commented Mar 9, 2023

tacaswell left a comment

Choose a reason for hiding this comment

jklymak commented Mar 9, 2023

jklymak commented Mar 9, 2023

jklymak commented Mar 11, 2023

jklymak commented Mar 17, 2023

jklymak commented Mar 17, 2023

timhoffm Mar 17, 2023

Choose a reason for hiding this comment

timhoffm Mar 17, 2023 • edited Loading

Choose a reason for hiding this comment

jklymak Mar 17, 2023

Choose a reason for hiding this comment

timhoffm commented Mar 17, 2023

jklymak commented Mar 17, 2023

jklymak commented Mar 5, 2023 •

edited

Loading

timhoffm Mar 17, 2023 •

edited

Loading