Repository navigation
[Doc]: Reintroduce glossary for matplotlib terms and concepts #28889
Description
Documentation Link
No response
Problem
We have a bunch of special terms and concepts that we use throughout the docs, e.g. "data coordinates", "view limits" etc. We currently do not have dedicated places in which such concepts are documented and that we could link to.
I'd like to have the ability to link such places in the docs. Currently, if we do such linking, the way is case-by-case, e.g. for view limits, I could reference .Axes.viewLim (which currently does not explain the machninery around it) or for "data coordinates" :ref:`data coordinates <coordinate-systems>` .
Suggested improvement
We have rightfully removed the glossary in #18696, because it did not carry useful information.
I now propose to reintroduce a gloassary specifically designed around the Matplotlib concepts and terminology. This will make linking simple, e.g :term:`data coordinates` .
The glossary entries should have only very brief descriptions of the term (1-5 sentences) and link out to more in-depth documentation (tutorials, API, etc.) if needed.
Activity
anijjar commentedon Oct 21, 2024
I wouldn't mind getting the ball rolling for this. @timhoffm Any specific terms you want included from the get-go. I can look at the retired glossary to make a list?
timhoffm commentedon Oct 21, 2024
The old glossary was retired because it did not contain any useful information - it was basically the wrong scope, i.e. not covering Matplotlib concepts and terminology. You don't have to look at it. For a start, these terms make sense (likely more to come when thinking further about it):
story645 commentedon Oct 21, 2024
That's more or less the outline on the getting started/user guide:
https://matplotlib.org/devdocs/users/index.html
which broadly, I think the glossary should probably cover the terms needed to navigate the user guide.
timhoffm commentedon Oct 21, 2024
I would phrase it the other way round: The glossary lists important terms and concepts. Naturally, the user guide covers many of them as well. The key difference is the kind of documentation. While the user guide is Tutorials/Explanation (I believe it's a bit of a mixture historically), the glossary is Reference.
Also, the glossary should be short, one sentence up to one paragraph. But it can link to the other types of documentation. For example Artist:
story645 commentedon Oct 21, 2024
Don't disagree but we should avoid circular definitions. I think even something like
Eta: Could probably drop everything past the first sentence too. I think mostly what's important is getting across that Artist is a core object model.
DOC: Reintroduce glossary
DOC: Reintroduce glossary
DOC: Reintroduce glossary (matplotlib#30782)