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
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.
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 ...".
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.
Yep, I was simply confused. Imperative all the way for method/function summaries.
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.