Standard location for implementation notes?

@astropy/astropy-core-maintainers - quite a while ago (#4821), @astrofrog suggested that it might be good to have implementation notes in some standard place, i.e., notes about the design of a given module. At the time, he considered a separate file, but it was felt that really this should be part of the documentation.

I am reopening this discussion because of #8902, in which @taldcroft adds an _implementation_note docstring to table.py, which has some very useful “developer-beware” notes. I think it would be good to have a standard way to do this, and in particular to ensure such notes become part of the documentation.

My own suggestion is a very simple one: let’s use the module docstring for implementation notes. Currently, these are essentially unused (see below for examples from time/core.py and units/quantity.py). Obviously, they will be typeset as part of the API by sphinx, which I think is file.

If we go this route, we could do worse than just start by following the numpydoc guide, which suggests the following sections:

1. summary
2. extended summary
3. routine listings
4. see also
5. notes
6. references
7. examples

Examples

# time/core.py
"""
The astropy.time package provides functionality for manipulating times and
dates. Specific emphasis is placed on supporting time scales (e.g. UTC, TAI,
UT1) and time representations (e.g. JD, MJD, ISO 8601) that are used in
astronomy.
"""

# units/quantity.py
"""
This module defines the `Quantity` object, which represents a number with some
associated units. `Quantity` objects support operations like ordinary numbers,
but will deal with unit conversions internally.
"""

[eteq]

A bit late to the party, but I also agree this is a good idea. I also fully agree with @hamogu and @mhvk that it’s good for users to see this, with one caveat: we want to make sure they know that implementation notes are not necessarily guarantees. That is, implementation notes are good places to say things like “internally this is stored as an X” but we don’t want the users to take that to mean “you can write code assuming it is always an X”, since in some places we intentionally hiding that in the public API so that we can potentially change in the future. (E.g., places where standard numpy arrays are used but conceivably dask or GPU-accelerated or whatever arrays might work in the future).

Honestly, I’m -0 to it being in module docstrings though. I like the simplicity but see @astrofrog’s concern which is similar to mine above. But I think that could be ameliorated by having a standard section at the top that says “warning: these are implementation details that might change, and you might want to ignore them if you are just looking for hte API” or similar.

[mhvk]

Reminder partially to me: coordinates/builtin_frames.py is a good example of a submodule with a __doc__ aimed at developers (though currently it is no longer exposed in sphinx, as __doc__ is overwritten by the transform graph; see https://github.com/astropy/astropy/pull/9035#discussion_r307508221 for @eteq’s neat solution).