can datetime be put near dates?

I'm not clear what you mean here. The first sentence notes datetime and datetime64.

line 217/219 -> batch all the datetime stuff together

I dunno that it's untuitive that this is in axes-I had a really hard time finding it in the TOC - I know that the implementation is on the axes, but using it feels more akin to the first box of more general functionality.

The first box is the quick start guide. This support could/should be mentioned there (if its not already), but no where near in this detail.

but no where near in this detail

I honestly think this guide is trying to do too many things, which is why I'm harping on more signposting please.
I think the general units stuff should be a sentence or so here and fleshed out in the units tutorial that I think @ksunden is working on. Which that's also on second thought where I'd put the info about convertors and formatters and stuff. That leaves two or three examples of dates and categories for the quick start guide. Basically I think folks generally shouldn't need loads of detail for something we're in theory providing as an automagic unless they're trying to make their own.

But also to my original point, I don';t think folks would think to look for it in Axes cause this is a data thing and everything else is layout or labeling

I think the general units stuff should be a sentence or so here and fleshed out in the units tutorial that I think

There is a sentence at the top that says:

The method to add converters to Matplotlib is described in `matplotlib.units`.
Here we briefly overview the built-in date and string converters.

The final section is because people are quite likely to see more general units support in other libraries or even in our examples. I would like to keep it.

I don';t think folks would think to look for it in Axes cause this is a data thing and everything else is layout or labeling

I disagree that this is not about labelling - that is the major advantage of unit support, providing useful tick locators and formatters.

that is the major advantage of unit support, providing useful tick locators and formatters.

Yes, but using unitid data hands over control of locators and formatters to the unit implementation. The users interaction with the unit framework is in the data they plot, not in the ticks/labels (annotations) they set. It's analogous to colormapping, which is also mapping data to the unit (color) that the heatmap visualizations can work with.

Yes, but using unitid data hands over control of locators and formatters to the unit implementation. The users interaction with the unit framework is in the data they plot, not in the ticks/labels (annotations) they set.

After passing unitful data to the plotting routines, which the user doesn't control, the only way to interact with the units machinery is via tick locators, formatters, and axis limits. Indeed these are the things that cause confusion, and the main motivation for this section. eg. user uses mplfinances converter which ignores weekends, and then tries to use our Locators and Formatters and get nonsense results. I'd say a lot of people who use datetimes end up setting the Locator and customizing the Formatters.

I'd say a lot of people who use datetimes end up setting the Locator and customizing the Formatter

But we have documentation to explain the datetime formatters/convertors. They literally can't use any other locator/formatter if they're using categorical or everything will break.

Which actually, I would support this document focusing on datetime (+ probably consolidating or linking out to some of the other datetime guides) and the general discussion being in what's currently called the quick start guide (and I think should be transitioned into overview).

I think this section at the bottom here is sort of distracting - it's repeating a lot of the information from the top, which is where I expect this section to be -> introduce the topic, then show the two specifics that are implemented. I think the most important bits here should be pulled to the top and this section go away. Most important bits being:

1. mpl maintains a registry of units
2. external libraries can register their convertors
3. to see a list, type: print(munits.registery.keys())

99.9% of users never need to encounter how the unit support takes place or the idea of the registry. I think explaining it at the top is needlessly distracting.

I think explaining it at the top is needlessly distracting.

And I think jumping into "we handle dates and times differently" without a sentence first grounding why is disorienting. Like this whole document is giving all these tricks for debugging units, but then you wait til the bottom to explain what units are.

And also, I think this section can be more or less integrated with the first paragraph and end up at roughly the same length.

this whole document is giving all these tricks for debugging units, but then you wait til the bottom to explain what units are.

The document I submitted does not talk about debugging units until the clearly labelled subsection "Determine converter, formatter, and locator on an axis".

And I think jumping into "we handle dates and times differently" without a sentence first grounding why is disorienting.

The first two paragraphs are about "why".

he document I submitted does not talk about debugging units

implicitly it does when you describe the expected behavior of datetime and categoricals - they work like all the other functions, so the only reason to tell me is so that when it behaves weird I can go to this doc that tells me "no, it's supposed to behave like normal"

The first two paragraphs are about "why".

No, the first two paragraphs are about "what" Matplotlib does with data. But also I like this section as a standalone and am ok enough w/ the bookending that I can waive this objection.

This is already an FAQ entry, can it please only be in one place?

It comes up naturally here as well. I don't see the harm in discussing it here in context.

It means maintaining two sets of documentation, which introduces the documentation maintenance cost of keeping them in sync. I think it's fine to have here, but either this should link to the trouble shooting entry, or (my preference honestly), the troubleshooting reference should be deleted and point folks here.

I think we need both - this is a super-common problem. I don't think the duplication is at all a maintenance burden.

I don't think the duplication is at all a maintenance burden.

It means that if there's a change to the unit framework that changes this behavior, there are 2 places this information needs to be updated. And there are 2 places to link folks when they ask "hey, what should I do here?", which is the doc equivalent of the API complaint we get all the time about having way too many ways to do the same thing. And we've been working at that on the API side & trying to be more explicit about when to reach for which function & same here - is there a reason that the FAQ needs to carry around a second version of this troubleshooting rather than linking here?

An added bonus of linking the FAQ to this document is that then the user is pointed to it & if they're having trouble with datetimes they can get more context here.

I understood your point the first time. I simply disagree.

Ok, I'll do a follow up PR where I delete the FAQ entry and link here.
https://en.wikipedia.org/wiki/Single_source_of_truth

I agree with Jody, there the small harm in discussing this in multiple places is out weighed by making any given section readable on its own.

How would linking the FAQ entry back to this guide harm readability? the semi-consensus in #17920 was to transitioning the FAQ into more of an alternative TOC, and linking the FAQ entry back into the guide is inline w/ that consensus.

I would stick a bounding box on all of these. The thin orange text is really hard to read against the blue/white background.

Technically there is also one for decimal.Decimal, though admittedly it is just calling float(val).

(This is also included in the printout at the bottom of the page)

Yeah, thats such a weird edge case, I'd prefer not to mention it. I assume few people use this.

The repr of these clases is not super useful and so I think dropping at least the object at 0x1234ABCD will improve readability.

Could go even further and do type(...).__name__, though that loses the namespacing, and don't want to complicate the code to get __module__.__name__.

Agreed - I admit I didn't figure out an easy way to just say the type, which really should have been more obvious to me ;-)

I could see expanding this into a couple subheadings, e.g:

The following downstream libraries provide support for physical units integrated with matplotlib:

• astropy
• pint
• unyt

The following provide support for additional date/time formats:

• pandas
• nc-time-axis (used by xarray)

I don't want to get into a comprehensive list, but a little more context as to what is provided by each popular downstream may be helpful to a reader who comes to this page.

Changed to

# There are a number of downstream libraries that provide their own converters
# with locators and formatters.  Physical unit support is provided by
# `astropy <https://www.astropy.org>`_, `pint <https://pint.readthedocs.io>`_, and
# `unyt <https://unyt.readthedocs.io>`_, among others.
#
# High level libraries like `pandas <https://pandas.pydata.org>`_ and
# `nc-time-axis <https://nc-time-axis.readthedocs.io>`_ (and thus
# `xarray <https://docs.xarray.dev>`_) provide their own datetime support.
# This support can sometimes be incompatible with Matplotlib native datetime
# support, so care should be taken when using Matplotlib locators and
# formatters if these libraries are being used.