Repository navigation
[Doc]: colorbar documentation should be modernized #25541
Description
Problem
Searching "Matplotlib colorbar" brings up lots of info from our website, but a lot of it is pretty old. Older ways for doing things, in particular the examples that use AxesDivider, should get crosslinks to the more standard idioms.
Activity
Higgs32584 commentedon Mar 24, 2023
Is there already sufficient, updated documentation that just needs to be more prominent in the search or do we need to rewrite some pages? we probably should get a list going of depreciated content
I know this is kind of off-topic, but maybe we should include dates when the last time a page/function was changed in the documentation just to give people an idea of how much they should trust it, cause I am unable to tell how recent some documentation is without parsing down the examples directory
timhoffm commentedon Mar 24, 2023
I'm afraid this information is less useful than it sounds. There's ancient documentation that is still correct. OTOH a recent update could only fix a typo/link/small part of a page and does not guarantee all the page content is up-to-date.
Higgs32584 commentedon Mar 24, 2023
I still think disclosing the lifespan of these things because as time goes on, the risk of failure heightens. Most news networks have articles that display "last updated", as to give readers references to when the last time someone looked it over, and made edits, or changes.
And "recent update" is still an update, and while it certainly does not guarantee that the page is 100% right, neither does having no dates at all. I believe it still gives us a convenient reference point as to when the last time someone touched a page was.
jklymak commentedon Mar 24, 2023
I think that should audited. I think all the right documentation is somewhere, but maybe some more top-level should have a permanent home somewhere
For instance https://matplotlib.org/devdocs/users/explain/axes/colorbar_placement.html (which is newly in this location for 3.8) maybe should be rewritten as just
Colorbarsand be more general than just placing them. Or perhaps a page should be added to https://matplotlib.org/devdocs/users/explain/colors/. I think right now all we have that is general is https://matplotlib.org/stable/gallery/color/colorbar_basics.html which should probably be somewhere other than buried in the gallery.Higgs32584 commentedon Mar 24, 2023
I am also thinking here, as I was going through various examples, this page seems to not include import statements for various statements, I do not know if this is related, but a lot of these examples cannot be run by themselves. I assume that the standard is that each example can run without additional code, or with the expectation that you ran the previous notebook block before it.
It also says that you can download the full source code below, either as a .py or a .ipynb file, but neither properly formats so every line of code is commented/in a markdown file.
https://matplotlib.org/stable/tutorials/toolkits/axes_grid.html
Does this warrant opening up a separate issue? Or does this fall into this thread of outdated documentation? I found this when I was searching codex AxisDivider.
rcomer commentedon Mar 26, 2023
Good spot! It looks like that particular tutorial is entirely written in the docstring. I would say that warrants its own issue.
rcomer commentedon Jan 1, 2024
@jklymak was this addressed by #26914?