ABCD (Always Be Code Documenting)

Astropy
1

Where we don’t do this:

900×283 110 KB 

References
——————————
.. [dilbert] Scott Adams @ https://dilbert.com/strip/2007-11-26
2 Likes
2

The x-ref PR is :crossed_fingers: 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

  • 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. Generally identical in intent, but different in practice.

  • does number include complex?

  • absolutize document links in SkyCoord that prevent 3rd party packages that have x-ref turned on from subclassing SkyCoord .

1 Like