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

Revised content guidelines for Extended summary and Notes Numpydoc sections

    Details

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

      Description

      This RFC concerns new wording for the "Extended summary" and "Notes" content guidelines in DM's Numpydoc style guide.

      Background

      The issue is that the current wording, coming from the original Numpydoc style guide, seemed to encourage us to put all important conceptual documentation about an API in the extended summary (located right below the summary sentence), and reserve the Notes section only for fairly unimportant implementation details. See the current documentation on Extended Summary and Notes.

      The result is that in many docstrings we're writing fairly lengthy and detailed extended summary sections. I'm fairly confident that this isn't the intent of the original numpydoc guidelines, and it certainly isn't what you can see in Numpy, Science, and even Astropy documentation.

      The reason that I am invested in ensuring that the extended summary remains a summary (in the sense of brevity) is that long extended summaries impact the usability of our API reference pages (in my opinion). Users, I believe, expect to see the Parameters documentation in close proximity to the API signature at the top of an API reference. It's useful to be able to glance back and forth between the signature and Parameters section to see default values, for example. Now if the extended summary is quite long, it becomes necessary to do a fair amount of scrolling to glance between the signature and the parameters. On the other hand, the Notes section is an ideal place to put the bulk of an API's conceptual documentation. Notes also leads directly into the Examples section.

      Proposed guidelines

      In DM-16826, I have attempted to reword the guidelines for the extended summary and notes section to clarify their usage. This RFC seeks to adopt these new wordings. Draft text:

      The DM-16826 ticket also mirrors these changes to the C++ documentation guide.

      Implementation

      I propose that this RFC will be implemented by closing DM-16826. I don't expect us to proactively review and edit all of our docstrings. Rather, I expect us to follow the new guidelines going forward and edit existing docstrings and we encounter them in regular work.

        Attachments

          Container Issues

            Issue Links

              Activity

                People

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

                  Dates

                  • Created:
                    Updated:
                    Resolved:
                    Planned End:

                    Summary Panel