Uploaded image for project: 'Request For Comments'
  1. Request For Comments
  2. RFC-559

Revised Numpydoc guidelines for Parameters, Returns & Yields sections

    Details

    • Type: RFC
    • Status: Implemented
    • Resolution: Done
    • Component/s: DM
    • Labels:
      None

      Description

      This RFC concerns updated guidelines around the documentation of Parameters, Returns, and Yields sections with Numpydoc. These guidelines reflect issues that the team has encountered while implementing Numpydoc.

      The implementation ticket is DM-16827 (see PR).

      Proposal A: Definition list formatting for Struct types

      For Struct types (and dict types with known keys), I'm proposing that we document individual attributes/keys using a definition list syntax, rather than the list syntax that was previously recommended. Definition lists are more semantically appropriate.

      See draft documentation.

      Proposal B: Specific guidelines for handling *args and **kwargs

      This RFC also introduces guidelines on how to document ***args
      and * *{{kwargs}} parameters, which are largely absent from the current guidelines. The choice to name the parameters *args and ** *kwargs rather than args and kwargs comes from reviewing existing practice. (I know I've told some people to use kwargs, sorry about that.)

      See draft documentation

      Proposal C: Improved documentation for dict types

      See draft documentation

      My recommendation is to write a dict-type parameter like this:

      measurements : `dict`
          Measurements of metrics. The keys are names of metrics (`str`), and
          values are `astropy.quantity.Quantity` instances, which combine
          both value and unit information.
      

      That is, just write dict as the type and describe keys and values in the description.

      C: Alternative 1

      An alternative that Krzysztof Findeisen has shown in practice is to put the full type information in the type field:

      measurements : `dict` from `str` to `astropy.quantity.Quantity`
          Measurements of metrics.
      

      C: Alternative 2

      Another variation with different formatting might be:

      measurements : `dict` (`str`: `astropy.quantity.Quantity`)
          Measurements of metrics.
      

      I'm opening to these alternatives if they're popular.

      Proposal D: Specific recommendation on naming return variables

      Lastly, I propose adding text recommending against unnamed return variables. See draft documentation

      For example:

      def sayHi():
          """Say hello.
       
          Returns
          -------
          `str`
              A greeting.
          """
          returns "Hello world"
      

      The problem with this usage pattern is that str doesn't get linked; it's displayed as the name of the returned variable.

        Attachments

          Issue Links

            Activity

            Hide
            rowen Russell Owen added a comment -

            I would be equally happy with colon or comma. I don't understand the Sphinx prior art well enough to have an opinion, other than please either require parenthesis or square brackets in our coding standard, don't allow a mix.

            Show
            rowen Russell Owen added a comment - I would be equally happy with colon or comma. I don't understand the Sphinx prior art well enough to have an opinion, other than please either require parenthesis or square brackets in our coding standard, don't allow a mix.
            Hide
            rowen Russell Owen added a comment -

            Tim Jenness this is a bit of distraction but...do you anticipate using type annotations everywhere or only in select places? I haven't used it much yet. At one level it seems useful and at another level I worry that it may introduce some of C++'s inflexibility where it's not always wanted.

            Show
            rowen Russell Owen added a comment - Tim Jenness this is a bit of distraction but...do you anticipate using type annotations everywhere or only in select places? I haven't used it much yet. At one level it seems useful and at another level I worry that it may introduce some of C++'s inflexibility where it's not always wanted.
            Hide
            krzys Krzysztof Findeisen added a comment -

            Jonathan Sick following Sphinx's lead seems like a good idea (though if I understand things correctly, the autolinking only works if we were to start writing function docs in RST instead of docstrings?). No objections from me.

            Show
            krzys Krzysztof Findeisen added a comment - Jonathan Sick following Sphinx's lead seems like a good idea (though if I understand things correctly, the autolinking only works if we were to start writing function docs in RST instead of docstrings?). No objections from me.
            Hide
            tjenness Tim Jenness added a comment -

            Russell Owen I don't think we have plans to require it. Python ignores them anyhow. They are solely for linters but if we are writing out the types anyhow in the docstrings it seems a waste if we could put them in a slightly different place and get some additional feedback from tooling.

            Show
            tjenness Tim Jenness added a comment - Russell Owen I don't think we have plans to require it. Python ignores them anyhow. They are solely for linters but if we are writing out the types anyhow in the docstrings it seems a waste if we could put them in a slightly different place and get some additional feedback from tooling.
            Hide
            jsick Jonathan Sick added a comment -

            I think we've reached consensus on all four proposals, including a decision to move to a PEP 484-like syntax for describing container types. Work will move to DM-16827 to implement this.

            Show
            jsick Jonathan Sick added a comment - I think we've reached consensus on all four proposals, including a decision to move to a PEP 484-like syntax for describing container types. Work will move to DM-16827 to implement this.

              People

              • Assignee:
                jsick Jonathan Sick
                Reporter:
                jsick Jonathan Sick
                Watchers:
                John Parejko, Jonathan Sick, Kian-Tat Lim, Krzysztof Findeisen, Meredith Rawls, Russell Owen, Tim Jenness
              • Votes:
                0 Vote for this issue
                Watchers:
                7 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:
                  Planned End:

                  Summary Panel