Meta Issue: ABCD (Always be Code Documenting) followups to X-Ref PR #11118

[nstarman]

Copied from https://community.openastronomy.org/t/abcd-always-be-code-documenting/56/2?u=nstarman

The x-ref PR is 🤞 wrapping up and I want to document the various possible followups that have cropped up. In an unexplained but very particular order:

• standardize usage of optional and keyword-only for optional OR keyword-only arguments.
  • all arguments to which these apply should be labelled as such
  • ¿ standardize as being parenthesized (optional, keyword-only)
• unignore the numpy array subclassing terms (in conf.py)
• Implement some sub-package specific glossary terms, e.g. “frame-instance” (as suggested by @adrn)
• get all parameters that had to be converted to rst code markup x-ref’ed
• Expand input types by making more things “-like” by passing them through their relevant constructors. E.g. more things that only accept an angle should also be able to accept angle-like strings.
• Parameter descriptions have a lot of inexactness, like claiming something must be a function, when it can be any callable. Correct this.
• Get the x-ref links to look the same as the other links. See Getting started — numpydoc v1.2.dev0 Manual
• xref physical types #11595: Implement physical types annotations on quantity (and quantity-like) parameters
• Similarly, where it is more clear, use typing-like syntax to explain sub-types: dict[str, float] over "dict with string keys and float values"
• finalize array shape syntax and how it applies to non-NumPy arrays. What is a (3,2) tuple? or even what is the difference between 2 tuple and (2,) tuple?
• array versus ndarray. [ndarray is preferred, see this comment by @dhomeier ]
• does number include complex?
• Resolve intersphinx to astropy as current build #11690 : use inter-sphinx document links in SkyCoord. Currently the relative links prevent 3rd party packages that have x-ref turned on from subclassing SkyCoord .
• use inter-sphinx document links for HDU. Currently the relative links prevent 3rd party packages that have x-ref turned on from subclassing HDU .
• correct usage of path-like : Support generic os.PathLike instead of pathlib.Path #11580