Ordering of items in Reference/API sections (esp. astropy.units)

[mhvk]

What is the problem this feature will solve?

The reference/API section for some subpackages can be quite long - e.g., astropy.units has several dozen functions and classes (see https://docs.astropy.org/en/stable/units/ref_api.html). Hence, order matters to find something. On stable, order is alphabetical, but on dev it has become by alphabetical by submodule things are imported from, because that is how __all__ is defined (which was introduced by #15862).

The question now is what to do. Options:

1. Sort __all__ and always make things alphabetical
2. Somehow introduce headings between items. This would have the benefit that it would make it unnecessary to also display, e.g., the contents of astropy.units.equivalencies. But might also make things less findable.
3. Other?

Describe the desired outcome

A clean reference/API page without needless duplication.

I put a milestone here since I think we should decide on some ordering before we release the next stable docs (reverting to sorted alphabetically if we cannot think of something better).

Additional context

No response

[pllim]

Is this resolved? I am removing the milestone since v6.1.0 has happened and we usually do not milestone issue unless it is a release blocker. Thanks!