Hello,
When documenting PsychoPy functions/classes, what is the preferred formatting style? The developer’s guide doesn’t say anything too specific other than to use a Sphinx friendly style.
This came up once before and the answer is that, so far, we don’t have any consistency so choose what you like!
THEN I would have said to use the REStructuredText format because that’s what PyCharm does.
THEN I just discovered that PyCharm can be told which format to use!
So what does everyone like? And can anyone be bothered going through and changing existing docstrings? (My usual stance that I don’t like purely-cosmetic resturcturing doesn’t apply here because rewriting docs doesn’t obscure more-important code changes.)
I’ve been using PyCharm’s reST, but I feel that NumPy style is more suitable for academic work.
Standardizing on a doc type will produce very nice output when hitting Ctrl+Q in PyCharm. Right now it’s a bit messy in some older modules.
I think my preference is for numpy too, and nobody else is joining in, so let’s you and me decide! 
Hmm, I don’t like how PyCharm removes reST headings for Parameters and Returns when using quick docs, really just a superficial complaint.
Numpy style is the most readable IMO and doesn’t require indentation for sections which is nice when keeping line width at 80. I like how examples are references are handled, which are important information for novice programmers and researchers. I would say use Numpy style.
Here is an example of how to generate docs with it…
In my down time I can work on making documentation consistent across PsychoPy.
Here is an example of dkl2rgb’s documentation in ‘numpydoc’ format. You can insert directives for images and math rendering too. I copied over citations and implementation details from the existing documentation.
"""Convert from DKL color space (Derrington, Krauskopf & Lennie) to RGB.
Parameters
----------
dkl : array_like
1-, 2-, 3-D vector of DKL coordinates to convert. The last dimension
should be length-3 in all cases specifying a single coordinate.
conversionMatrix : array_like, optional
3x3 conversion matrix to transform DKL values to RGB values. If no
matrix is supplied, a default matrix is which is generated from generic
Sony Trinitron phosphors is used (note that this will not be an accurate
representation of the color space unless you supply a conversion
matrix).
Returns
-------
ndarray
An array of RGB values with the same shape as `dkl`.
Warnings
--------
A warning is logged if a conversion matrix is not specified.
Notes
-----
To use DKL color space the monitor should be calibrated with an appropriate
spectrophotometer, such as a PR650.
In the Derrington, Krauskopf and Lennie [1]_ color space (based on the
Macleod and Boynton [2]_ chromaticity diagram) colors are represented in a
3-dimensional space using spherical coordinates that specify the elevation
from the isoluminant plane, the azimuth (the hue) and the contrast (as a
fraction of the maximal modulations along the cardinal axes of the space).
In PsychoPy these values are specified in units of degrees for elevation and
azimuth and as a float (ranging -1:1) for the contrast.
Note that not all colors that can be specified in DKL color space can be
reproduced on a monitor.
References
----------
.. [1] Derrington, A. M., Krauskopf, J., & Lennie, P. (1984). Chromatic
Mechanisms in Lateral Geniculate Nucleus of Macaque. Journal of
Physiology, 357, 241-265.
.. [2] MacLeod, D. I. A. & Boynton, R. M. (1979). Chromaticity diagram
showing cone excitation by stimuli of equal luminance. Journal of the
Optical Society of America, 69(8), 1183-1186.
Example
-------
rgb(Nx3) = dkl2rgb(dkl_Nx3(el,az,radius), conversionMatrix)
rgb(NxNx3) = dkl2rgb(dkl_NxNx3(el,az,radius), conversionMatrix)
"""
1 Like