DOC: use different 'sections' in the docstring examples?

[jorisvandenbossche]

For docstrings that have quite some examples, it might be useful to provide some more structure in there.
The numpydoc parsing does not really allow actual sections, but by using for example a bold font, you can create a bit the 'sense' of subsections.

Is this something we would want to encourage in the docstring guide?

Example of the current examples section of to_datetime:

And one with 'subsections' (just for the idea, not necessarily perfect titles :)):

cc @datapythonista @jreback @TomAugspurger

[TomAugspurger]

👍

[gfyoung]

+1 from me as well. We are by no means strictly wed to the numpy-doc standards.

[jorisvandenbossche]

Closing this as @datapythonista included it in the docstring guide (#19704)