Ha, for sure this requires discussion, as I think my opinion would be that most of the tutorials should be moved to rst.

OTOH, I see the appeal of tutorials. In particular they are much easier to test that the figures are what you expect before building the docs.

If for the sake of argument we moved all the docs to tutorials, I'm not sure how they would appear in table of contents or summary screens. The way sphinx-gallery does it now is each subdirectory gets a subsection, but then each document gets a thumbnail. I'm not clear if you can nest the directories further, and I don't know what we do about "tutorials" that have no actual figures in them. Similarly, getting sphinx gallery to order requires gallery_order.py, which isn't great.

If we merged the "tutorials" and the rest of the docs the other way, it might make sense to look at using notebooks in some way. Or even just converting the *.py files to *.rst offline and putting them in the right hierarchy with a normal sphinx toc. There are probably a few ways to do that these days that don't just make a flat gallery.

We have https://matplotlib.org/stable/gallery/user_interfaces/index.html , https://matplotlib.org/stable/gallery/widgets/index.html , and https://matplotlib.org/stable/gallery/event_handling/index.html in the examples so I do not think it is fair to say that all of the documentation about interactive figures is in "explanation". I suspect the reason many people think Matplotlib is not interactive is that their initial interaction was with the inline backend (which is indeed static).

The organization we have been pushing towards is based on https://documentation.divio.com (some discussion in #20735 and linked) so I do not think that collapsing "explanation" into tutorials is the right choice.

If anything, I think a number of the things we have in tutorials should move the other way into "explaination" (and probably a number of them should move into "examples"....very few of our tutorials are actually "tutorials" in per the divio classification).

Tons of discussions 😄. Additionally, there is how to and [missing] a good place for reference. We need to have all four categories of documentation. We already aspire that on the front page.

We need to specify dedicated locations where each kind of documentation shoud live. One fundamental aspect of that is that the location is bound to a technology (.rst, notebook, gallery). Having different technologies makes it more difficult to move content between the types when we realize, I'd better be in another category. Also there may be user preference. If somebody is more comfortable writing a notebook or a .py file rather than .rst they may choose to put content where their favorite technology is.

Maybe we need to have multiple technologies per category (at least for a transition period). For example, we cound make Sphinx entry pages per category. Each entry page can have a toc of regular pages plus a sphinx gallery. That way, we could move content to the right category without the need of rewriting.

I guess I hadn't quite realized that its pretty trivial to add individual tutorials to the "User Guide" table of contents, and we could have a hierarchy of them mixed with the other "User Guide" topics (e.g. they would not need to all be linked at the top level.). That is actually super-easy and pragmatic. Yes, it means that some tutorials are reachable from two spots, but that doesn't seem like it's such a big deal. It also means that the link still says /tutorials/introductory/getting_started, but again, doesn't seem too big a deal.

OTOH, I see the appeal of tutorials. In particular they are much easier to test that the figures are what you expect before building the docs.

It should be "relatively easy" to write a "plot-directive runner" that takes a rst file as argument and extracts the plot directives and plots them, at least for devel purposes.

The organization we have been pushing towards is based on https://documentation.divio.com/ (some discussion in #20735 and linked) so I do not think that collapsing "explanation" into tutorials is the right choice.
We need to have all four categories of documentation. We already aspire that on the front page.

Agree, and going by the discussion here everybody has different ideas of what should move where so I think the first step is we decide on and document our criteria for classifying a document as a:

• learning-oriented tutorial
• goal-oriented how-to guide
• understanding-oriented discussion

Once we do that, I think the second step is cataloging the current documention, maybe just by tagging documents¹. This would let us flag which ones are maybe trying to be too many things (explanations and tutorials and how tos) and we can then decide on a case by case basis what should be moved or split up or rewritten. I think the third step would be converting formats, and is probably the easiest part -> my initial suggestion was based mostly on it being easier to convert 8 documents than however many are in tutorials rather than any specific semantic association with tutorials.

ETA: I also think we have this taxonomy problem in the gallery, where there are short how to style examples, tutorials on using different methods, and reference figures.

ETA 2: @melissawm mentioned that someone did this sort of cataloguing work as part of a numpy GSOD.

So I think the latest divio classification is maybe slightly clearer guidance/maps more to how I think we organically have structured things, b/c at least to me a major attribute of "background/explanation" seems to be that it's documenting architectural choices, while the how to and tutorials are more geared towards usage.

Hi everyone, stumbled upon this issue via a recent Twitter discussion. I have sifted through quite a few "I hate matplotlib" threads recently and noticed that people have various workflows when they try to figure out how to create a visualization. E.g. for some of them the gallery is the entry point, for others a function documentation etc. I think it would be a worthwile exercise to interview a few struggling devs to find out their workflow and adapt the entry to the documentation to their workflow. Divio has a nice approach, but it is still quite focused on how the maintainer's point of view. While for matplotlib the main problem is that barely anyone is up to date enough to use even such a documentation effectively. So it may turn out that the divio structure still doesn't capture the specifity of the typical problems that people encounter when trying to use matplotlib.

Has anyone done something like this in the past? What do you guys think? I have done similar things for other projects, so I could give it a try on a small scale, interview a few people about their workflow and see whether we come to some insights.

Has anyone done something like this in the past?

@jeromefv as part of his GSOD a few years back did a user survey and collected some info.

I'm very much for this endeavor and like one of the reasons I haven't pushed for it is not having the time to lead the effort so thanks for stepping up!

My thinking is that maybe we could use something like the divio structure for folder/top level organization (where does what go?), but then structure our UX and signposting on landing pages and use of tags and the like around user stories (where do I find what?)

I would be very interested to take a look at @jeromefv's work. Maybe it's enough to come up with a first proposal. Is it publicly accessible somewhere?

My thinking is that maybe we could use something like the divio structure for folder/top level organization (where does what go?), but then structure our UX and signposting on landing pages and use of tags and the like around user stories (where do I find what?)

Makes sense!

A semi-related thought. A lot of users seem to be stuck in a syntax / way of doing things from v2.0 or earlier. I wonder what would be the best way to encourage them to discover new functionalities and/or port their code. They think they already know matplotlib, so they miss out on a lot of stuff. Have you experimented with something maybe like a targeted tutorial or a social media campaign that would go along the lines of "stop doing xy, start doing z"?

I'm all for improving our docs. However, I would be very careful about writing the docs "defensively" based on Twitter comments. We have hundreds of thousands of users. If a hundred of them pop up on some Twitter thread saying they don't like Matplotlib, or they find it confusing, that seems like a lot, but it's not necessarily representative of our user base.

Personally I think the biggest confusion is downstream libraries adding plotting methods to their data objects to try and be more declarative and ggplot-like, but then users having to drop down into pure Matplotlib to do any plot customization, which all has to be done imperatively. If instead of doing df.plot(ax=ax); ax.set_title('Boo') folks just did ax.plot(df.index, df['data']); ax.set_title('Boo') their life would be easier in the end.

I'm all for improving our docs. However, I would be very careful about writing the docs "defensively" based on Twitter comments. We have hundreds of thousands of users. If a hundred of them pop up on some Twitter thread saying they don't like Matplotlib, or they find it confusing, that seems like a lot, but it's not necessarily representative of our user base.

That's a great point and I didn't mean it that way. I'd be super interested to see what is the actual demographics, what other tools etc. people use, what are the main struggles formulated in their own words. I think there is a value in collecting various types of confusions and misconceptions people have, because we could target them in documentation directly and then actually user-test the documentation. Newer libraries (like let's say seaborn) doesn't seem to have this problem in such a magnitude, because they have started from a cleaner state.

Have you experimented with something maybe like a targeted tutorial or a social media campaign that would go along the lines of "stop doing xy, start doing z"?

Yup on the social media and these work really well and I don't have time right now to do them but will be very grateful if someone else wants to. ETA: our communication platform for coordinating that sorta thing is https://gitter.im/matplotlib/community

I agree w/ Jody on not writing our docs defensively. I honestly think some of our docs already have that flavor b/c it's common in academia and it can often make the document more confusing than needed. That being said, one of things we've discussed is different ways of surfacing newer functionality b/c I agree w/ @paniterka that like a lot of folks are stuck on the 2.0 way (I think honestly probably as a function of that's what a lot of resources were written against and not updated and folks tend to write new resources guided by the way they learned things). I tilt more towards programmatic ways of surfacing new content (like #15920) b/c long term I think that's more maintainable, but could definitely see the utility in a one off "2.0 to 3.0" doc.

I would be very interested to take a look at @jeromefv's work. Maybe it's enough to come up with a first proposal. Is it publicly accessible somewhere?

I'm happy to share the data from that usability testing survey in 2020! There's also this content with saved responses from open questions.

It's been a while since I've contributed to Matplotlib documentation—I've been fortunate with technical writing work for the last few years after having gotten my foot in the door through the GSoD with this team! I'd be thrilled to help with this issue and support as folks may need!

Thanks a lot @jeromefv ! The results are super interesting. I skimmed through the free-text answers and there is definitely a pattern where people suggest curating and maybe pruning some of the code and viz examples that are currently in the docs. How do people here feel about removing content from the docs in general?

I found it interesting that at the same time, the majority of respondents clearly want more examples rather than fewer. But the two could still be consistent: it can be that MPL docs have too many examples that are not relevant for what the users are looking for (or are hard to navigate), and not enough clear and relevant examples.

I noticed that the majority of people gave 4 out of 5 to describe their comfort in working with MPL (I assume 5 means high comfort). I am wondering if it is possible to filter the free-text messages and see only the answers from those respondents who gave 3 or less. The same for those users who don't use MPL that often (majority of respondents gave 5 out of 5, so it's possible they are power users who don't struggle as much). Is it possible to extract the raw data to see answers from those subpopulations?

On an explorative note: it would be super interesting to have a survey on familiarity of various functionalities of MPL. Say, how familiar people are with the concept of gridspec or locators/formatters. Or how comfortable they are in performing a particular task using MPL like adjusting tick positions. This could help decide which tutorials need to be highlighted and which moved to the "advanced MPL" part.

Ignoring the content that may go into this "combine" it would be nice to agree on a strategy

Move relevant tutorials to users/ hierarchy as rst files

See #24979 for an example of this where the rst of a turtorial is translated to use plot-directives to make the plots.

Pros:

• document only in one place in the tree
• perm-link indicates where it is in the tree

Cons:

• plot_directives do not maintain state across invocations, so there are no global imports (though pyplot and numpy are both imported implicitly) and you can't define helper functions that go from invocation to invocation.
• More work to move
• Some future explanatory material is definitely easier to write as sphinx-gallery tutorials rather than trying to write as rst.

Simply add the relevant tutorials and examples to the Table of Contents (users/explain/index.rst)

See #24987 for an example of this, where users/explain/index.rst links to many tutorials and examples to develop a narrative.

Pros:

• very easy
• navigation looks fine (eg the left-side nav bar stays with /users/explain rather than jumping into the tutorial table of contents.
• pro/con, but the material is curated in two different ways.

Cons:

• the permalink does not indicate that more similar information can be found in /users/explain (eg it will say /tutorials/intermediate/boo.html instead of /users/explain/boo.html)
• The tone and scope of some existing tutorials does not necessarily translate well to a users guide.

Are there other mechanisms I haven't considered? It would be great if sphinx gallery would allow rst files mixed with the *.py files. It actually seems like a trivial thing for them to do. However, so far as I can tell, they do not. I guess it might be possible to have /doc/users/explain_tutorial have some rst in it, and then let sphinx-gallery populate with the rest of the rst from /explain_tutorial? But that seems very confusing to have the documentation source in two different places.

Just to mention there are other strategies as well

• create a Sphinx-Gallery under users and move the existing .py files there.
• Make Sphinx-gallery support mixture with .rst (coding and discussion effort with sg but may be considered)
• Make Sphinx use content from .py files, possibly via a custom include directive, that is somewhere between our plot directive and what sg is doing.

The latter two need upfront coding effort, but we could opt for that if it makes our docs more consistent and easier to manage.

Make Sphinx-gallery support mixture with .rst (coding and discussion effort with sg but may be considered)

for the purposes of this reorg, which far as I can tell focuses on users and tutorials, gonna reiterate that there are 9 .rst files in explain so converting them to .py and making that the standard for all the narrative docs might be the easiest? I don't think we have to use the thumbnail index...and I'm also not opposed it since this is a viz library and therefore I think visual nav when possible is awesome.

@story645 Good idea - I apologize if I missed above. We could indeed populate doc/users/ with a gallery that gets written to doc/users/explain, convert the existing rst files to python, and move some of the tutorials etc.

Pros:

• easy to write long code- and figure-heavy examples.
• easy to just move existing tutorials and examples over.

Cons:

• the gallery would get dropped into the rest of /users/ which contains a bunch of rst-only files meant to be edited as part of the documentation process. Its somewhat confusing to drop a gallery directory in here (the existing ones are only dropped in at the top level).
• I'm not clear that it's possible to suppress the thumbnails? But maybe thats OK, though some of the text-only explainers should probably have at least one plot added for the thumbnail. The empty thumbnails look pretty terrible.
• Ordering galleries is a pain, requiring editing the gallery_order.py. Not exactly as easy as building a toc by hand.

Ordering galleries is a pain, requiring editing the gallery_order.py. Not exactly as easy as building a toc by hand.

#25028 is maybe hacky, but I figured that editing individual lists of folders is about akin to building individual toc

Ordering galleries is a pain, requiring editing the gallery_order.py. Not exactly as easy as building a toc by hand.

Since we wrote this extension to do the ordering, there's no reason we can't change it to read from README.txt in each directory. We could have it look for something that looks like a comment to reST so it does nothing in the sphinx-gallery-processed reST without having to do anything extra.

We could indeed populate doc/users/ with a gallery that gets written to doc/users/explain, convert the existing rst files to python, and move some of the tutorials etc.

This is a reasonable approach to start with as it‘s simple and low effort. We can always do more fancy things later.

• I'm not clear that it's possible to suppress the thumbnails?

I assume that‘s not possible. As a workaround, you could put the gallery and thus thumbnails in a subdir and create a manual index into the gallery pages. That way the thumbnails page is still there, but not the primary entry point in the navigation flow. But maybe thumbnails are still ok.

though some of the text-only should probably have at least one plot added for the thumbnail. The empty thumbnails look pretty terrible.

You can define custom images as thumbnail. It does not have to be a plot generated in that page.

I've opened sphinx-gallery/sphinx-gallery#1067 and sphinx-gallery/sphinx-gallery#1068 to get some discussion of mechanisms for mixing rst and python,.

Ordering galleries is a pain, requiring editing the gallery_order.py. Not exactly as easy as building a toc by hand.

Since we wrote this extension to do the ordering, there's no reason we can't change it to read from README.txt in each directory. We could have it look for something that looks like a comment to reST so it does nothing in the sphinx-gallery-processed reST without having to do anything extra.

If it does not affect the ReST directly, I see no real benefit in having the order in README.txt. Such a fake TOC could actually be confusing because it's a comment but still has an effect. That's quite magical. I think it would be more straightforward to instead have a simple GALLERY_ORDER.txt in every gallery folder.

An alternative solution would be to numerically prefix the example files (00_first_example.py) to create order. Advantage: You immediately see the order in the file system. Disadvantage: Reordering means renaming files, which is more cumbersome. Also, in the naive approach, the numbers would be reflected in the urls and changes would break links. If that approach is taken seriously, likely we would want the number prefixes to be stripped from the generated html files, which would have to be implemented in sphinx-gallery.

An alternative solution would be to numerically prefix the example files (00_first_example.py) to create order. Advantage: You immediately see the order in the file system. Disadvantage: Reordering means renaming files, which is more cumbersome. Also, in the naive approach, the numbers would be reflected in the urls and changes would break links.

FWIW this is the approach we used in MNE-Python and have been pretty happy with it for the last few years. We set up redirects to deal with the broken link issue -- it's something nice to have in any case since it can be useful to update doc/rst filenames, too, and you can just add yet another redirect there

https://github.com/mne-tools/mne-python/blob/4f487feddddd9f3844aaee47e3993a2c137a7bf8/doc/conf.py#L1093-L1095
https://github.com/mne-tools/mne-python/blob/4f487feddddd9f3844aaee47e3993a2c137a7bf8/doc/conf.py#L1234

Then it's pretty easy to add custom redirects, too, which is just useful in general, e.g.,

https://github.com/mne-tools/mne-python/blob/4f487feddddd9f3844aaee47e3993a2c137a7bf8/doc/conf.py#L1176

But it is a bit of work to get there.

I think sphinx-gallery/sphinx-gallery#1071 is a fine way to go, too, and less invasive for you all, so if that's what you decide is best, I don't see why SG couldn't support it

@larsoner you may want to check out our redirect directive. Edit: https://github.com/matplotlib/matplotlib/blame/main/doc/sphinxext/redirect_from.py

Just to highlight sphinx-gallery/sphinx-gallery#1071 explicitly here; it will allow bare rst files to be passed to galleries, and if index.rst is provided, that will be used instead of README.*.

The idea here would be that /doc/users/explain (for instance) would be a gallery under /explain/, and would contain a mix of *.py and *.rst and an index.rst in each directory and subdirectory. The *.py files would be turned into rst + images by sphinx-gallery, but the index.rst would be exactly what we specify.

@jklymak did some of this while revising the user guide and the rest should be part of more targeted PRs.