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

Use numpydoc and reStructuredText for Python docstrings

    Details

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

      Description

      We'll soon (~1-2 months) have a documentation system that renders HTML documentation from Python docstrings written with reStructuredText.

      At one of the PCW hack sessions (with a large majority of non-DMLT DM members in attendance) we had unanimous agreement that we should start writing Python docstrings in this form now, instead of prefixing docstrings with a "!" to invoke Doxygen markup.

      This will temporarily make HTML documentation for Python uglier (it will be rendered as reStructuredText source), but will eventually make it nicer, and it will make on-line Python docstrings modestly more readable (because reStructuredText source is more readable than Doxygen markup).

      If other hack session work goes quickly and this RFC is accepted ahead of schedule, this could give us an opportunity to start this transition for existing code during the meeting.

        Attachments

          Issue Links

            Activity

            Hide
            ktl Kian-Tat Lim added a comment -

            If it's a coding standard, I believe I'm BDFL for it. I'll read through py_docs.html when I get a chance, but I don't see any problem right now with adopting and implementing this change.

            Show
            ktl Kian-Tat Lim added a comment - If it's a coding standard, I believe I'm BDFL for it. I'll read through py_docs.html when I get a chance, but I don't see any problem right now with adopting and implementing this change.
            Hide
            jbosch Jim Bosch added a comment -

            Adopted; I think all concerns have been addressed and Kian-Tat Lim has explicitly signed off on it. I'm assigning the implementation issue (DM-7345) to Jonathan Sick.

            Show
            jbosch Jim Bosch added a comment - Adopted; I think all concerns have been addressed and Kian-Tat Lim has explicitly signed off on it. I'm assigning the implementation issue ( DM-7345 ) to Jonathan Sick .
            Hide
            rowen Russell Owen added a comment -

            Jonathan Sick said:

            The present tense action (e.g. “Joins two tables.”) is consistent with the numpy documentation style."

            The example should be "Join two tables", not "Joins two tables", as per this quote from PEP 257:

            The docstring is a phrase ending in a period. It prescribes the function or method's effect as a command ("Do this", "Return that"), not as a description; e.g. don't write "Returns the pathname ...".

            Show
            rowen Russell Owen added a comment - Jonathan Sick said: The present tense action (e.g. “Joins two tables.”) is consistent with the numpy documentation style." The example should be "Join two tables", not "Joins two tables", as per this quote from PEP 257: The docstring is a phrase ending in a period. It prescribes the function or method's effect as a command ("Do this", "Return that"), not as a description; e.g. don't write "Returns the pathname ...".
            Hide
            jsick Jonathan Sick added a comment -

            I could swear that I read guidance about the 'summary' sentence for a method or function should be written in the present tense with the method/function name ideally as the verb. However I can't seem to find that bit of research again. I think web companies generally use that construction since it's a bit friendlier.

            On the other hand, you're right, PEP 257 and numpydoc do seem to advocate the imperative voice here.

            I'm working on a ticket to implement both this RFC and the PEP 8 RFC, and I'll do some more research on this.

            Show
            jsick Jonathan Sick added a comment - I could swear that I read guidance about the 'summary' sentence for a method or function should be written in the present tense with the method/function name ideally as the verb. However I can't seem to find that bit of research again. I think web companies generally use that construction since it's a bit friendlier. On the other hand, you're right, PEP 257 and numpydoc do seem to advocate the imperative voice here. I'm working on a ticket to implement both this RFC and the PEP 8 RFC, and I'll do some more research on this.
            Hide
            jsick Jonathan Sick added a comment -

            Yep, I was simply confused. Imperative all the way for method/function summaries.

            Show
            jsick Jonathan Sick added a comment - Yep, I was simply confused. Imperative all the way for method/function summaries.

              People

              • Assignee:
                jbosch Jim Bosch
                Reporter:
                jbosch Jim Bosch
                Watchers:
                Cindy Wang [X] (Inactive), David Shupe, Jim Bosch, John Parejko, John Swinbank, Jonathan Sick, Kian-Tat Lim, Pim Schellart [X] (Inactive), Robert Lupton, Russell Owen, Tim Jenness, Xiuqin Wu [X] (Inactive)
              • Votes:
                1 Vote for this issue
                Watchers:
                12 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:
                  Planned End:

                  Summary Panel