Repository navigation
Help page on concepts and mechanisms in matplotlib #9967
Description
Feature request
We do not have a description of the concepts and mechanisms used in matplotlib. Some information is available in the respective classes or in examples. But I haven't found a concise overview giving the big picture.
It would be valuable for users (and also developers) to have a single help page collecting this information.
In particular:
Elements of a plot
- Figure
- Axes
- Axis
- Artists
- Patches
- ...
Coordinates and scaling
- Figure / Axes / Data coordinates
- Bbox
- aspect handling (original and active axes positions)
- transforms
- ...
The above are just the topics that came to my mind right now. It's work in progress and I plan to work on this later on. Comments and additions are welcome.
Activity
jklymak commentedon Dec 10, 2017
I think improving the usage guide is a place to start. It has most of your first subsection.
http://matplotlib.org/tutorials/introductory/usage.html#sphx-glr-tutorials-introductory-usage-py
timhoffm commentedon Dec 10, 2017
That's indeed a good place, already conating some of my points (though I haven't yet read it completely).
Maybe even more important than changing the contents is making this more accessible. To find it from the main page, I had to
Step 1 is fine, I would never have guessed that I have to follow the links in 2 and 3 to find that information. Maybe part of the problem is the naming. It's more a reference than a tutorial. Also, it's more "Concepts/Structure of matplotlib" than a "User Guide".
jklymak commentedon Dec 10, 2017
Agreed. I think that right now there is no user documentation. The advice I've received is to go ahead and add documentation to the existing structure, which for better or worse is the "tutorials" section, and then a re-organization will happen using that raw material. I think the only caveat there is that tutorials are
*.pyfiles, whereas straight*.rstwith..plot::directives might be a nicer editing format. But its pretty easy to translate the*.pytutorial files to*.rst(because it already happens during the build process). The other issue with tutorials is that they are not in any sensible order, which is another argument for*.rst. Sphinx Gallery arranges them by their length, of all things.anntzer commentedon Dec 10, 2017
FWIW I believe that although sphinx-gallery is really good for "unstructured" examples where the main focus is sample code and plot, it doesn't work so well for "tutorial/guide" style docs where text is the most important part.
I would support switching these parts of the docs back to plain rst.
story645 commentedon May 28, 2020
wonder how much this ties in w/ MEP #17446
timhoffm commentedon May 28, 2020
Loosely. #17446 is more specific in that it defines a method how to handle „porperty“ concepts. The docs part of #17446 and this one would live in the same part of the documentation.
story645 commentedon Nov 17, 2022
Wondering if most of this was addressed in #21641 w/ possibly a follow up issue that basically adds an intro to the transform tutorial to the quick-start guide?
Or are you looking to make a kinda glossary/single source of truth thing - we had one that was removed in #18696 b/c it just listed backends, but a "core concepts in mpl" might not be bad? A different alternative 'cause search is kinda not great is maybe using something like sphinx-tags to catalog some of the related pages?
timhoffm commentedon Nov 17, 2022
@story645 Thanks for the ping. I'll check what is available now and reconsider what I want here. Will get back on this later.
github-actions commentedon Nov 20, 2023
This issue has been marked "inactive" because it has been 365 days since the last comment. If this issue is still present in recent Matplotlib releases, or the feature request is still wanted, please leave a comment and this label will be removed. If there are no updates in another 30 days, this issue will be automatically closed, but you are free to re-open or create a new issue if needed. We value issue reports, and this procedure is meant to help us resurface and prioritize issues that have not been addressed yet, not make them disappear. Thanks for your help!
story645 commentedon Dec 21, 2023
Keeping this open until we can replace with a more actionable roadmap for doing this in docs?