Unifying numpy, scipy, and matplotlib docstring formats
I'd like to help the docstring formats of numpy, scipy. and matplotlib converge on a high-quality standard (hence the cross-posting). However, before that can happen all maintainers from all three packages need to agree on a format. In the interest of speeding things along, I've taken the liberty of extending [1] the docstring format proposed by Travis on January 10th on the scipy-dev mailing list [2]. I also volunteer to convert a non-trivial portion of the numpy, scipy, and matplotlib docstrings. If all goes well on the consensus front, I'll try to coordinate an IRC docstring sprint or two. The notable differences from the format Travis posted is that I have capitalized headers for readability; the other changes are mostly modest, or additions to handle the more demanding requirements of matplotlib docstrings. On the DocstringStandard page I have also put a completely re-done docstring for the 'contour' function from matplotlib. I think it is far more readable than the original [3]. JDH and other matplotlibheads, what do you think? Travis, do you find my additions reasonable? Scipy maintainers, would you consider adopting this format (especially if someone helps with the gruntwork)? Thanks in advance, Keir [1] http://scipy.org/DocstringStandard [2] http://article.gmane.org/gmane.comp.python.scientific.devel/5572 [3] http://matplotlib.sourceforge.net/matplotlib.pylab.html#-contour p.s. This is part of my plan to kick off http://scipy.org/PyLab
On 2/15/07, Keir Mierle <mierle@gmail.com> wrote:
On the DocstringStandard page I have also put a completely re-done docstring for the 'contour' function from matplotlib. I think it is far more readable than the original [3]. JDH and other matplotlibheads, what do you think? Travis, do you find my additions reasonable? Scipy maintainers, would you consider adopting this format (especially if someone helps with the gruntwork)?
It looks like you took the initial proposal rather than the result of that discussion. Please see the document that we came up with: http://svn.scipy.org/svn/numpy/trunk/numpy/doc/HOWTO_DOCUMENT.txt -- Robert Kern "I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco
On 2/15/07, Robert Kern <robert.kern@gmail.com> wrote:
On 2/15/07, Keir Mierle <mierle@gmail.com> wrote:
On the DocstringStandard page I have also put a completely re-done docstring for the 'contour' function from matplotlib. I think it is far more readable than the original [3]. JDH and other matplotlibheads, what do you think? Travis, do you find my additions reasonable? Scipy maintainers, would you consider adopting this format (especially if someone helps with the gruntwork)?
It looks like you took the initial proposal rather than the result of that discussion. Please see the document that we came up with:
http://svn.scipy.org/svn/numpy/trunk/numpy/doc/HOWTO_DOCUMENT.txt
Ah, I apologize for not checking the dates; I thought the HOWTO_DOCUMENT.txt was the older proposal. Nevertheless, I think the issues raised in my proposed version are significant enough to warrent further discussion; especially for the more demanding needs of matplotlib. I would like to re-open this discussion to be sure there is consensus among the numpy, scipy, and matplotlib folk before I invest signifcant time into massaging the docstrings into the right form. I am clearly biased as I invested time and thought into the proposed docstring format I posted [1], but nevertheless I do not like the style listed in the HOWTO_DOCUMENT.txt. The different sections have different styles of headings, i.e. the difference style for :Pamaraters: and Examples, which is not good for readability. Furthermore, it does not specify enough formatting, for e.g. keyword arguments with defaults. For specifics, here are my issues with the current HOWTO: * Non-capitalized headers Capitalized headers are far more visually obvious when viewed on a text terminal (i.e. via function? in IPython) * Two different header styles The distinction between :Parameters: and Examples -------- seems unnecessary; if this is necessary for reST, could a preprocessing step not fix this? The inconsistency appears unprofessional when viewed in a terminal. * No suggestions on how to handle functions which have multiple invocations, i.e. multiple function signatures. I have a proposal for this in [1]. * Parameters / Returns instead of INPUTS / OUTPUTS. This is no doubt a preference, but nevertheless I vastly prefer having INPUTS / OUTPUTS instead of Parameters / Returns. I understand that the parameter/return form is more common for Python, so I realize this is contentious. Nevertheless, inputs / outputs has the clear advantage of being informative to someone who is just starting programming and may not realize the meanings of parameters / returns; but input/output is absolutely clear even to the non-programmer. If it comes down to me writing a parser for my proposed format, I will do that. Keir [1] http://scipy.org/DocstringStandard
On Thu, 15 Feb 2007, Keir Mierle apparently wrote:
* Two different header styles The distinction between :Parameters: and Examples --------
These are not two items of the same type. ``:Parameters:`` designates a consolidated field (for describing the documented object). This is not a "section". Cheers, Alan Isaac
participants (3)
-
Alan G Isaac -
Keir Mierle -
Robert Kern