WIP: document our guidelines/coding conventions #2616
Conversation
GUIDELINES.txt
Outdated
| @@ -0,0 +1,7 @@ | |||
| Guidelines | |||
There was a problem hiding this comment.
Guidelines & Coding Conventions, perhaps?
There was a problem hiding this comment.
Coding conventions would be great. Especially naming conventions.
| @@ -0,0 +1,7 @@ | |||
| Guidelines | |||
| ========== | |||
|
|
|||
There was a problem hiding this comment.
Now just to figure out what common pieces of advice we give contributors :)
GUIDELINES.rst.txt
Outdated
|
|
||
| from skimage import data | ||
|
|
||
| img = data.coins() |
There was a problem hiding this comment.
@soupault Please, read my comment: #2538 (comment) and add your point of view :)
There was a problem hiding this comment.
Works fine to me either way. :)
|
@sciunto I wouldn't consider this dead, just dormant, thanks for awakening it. =) As a first step, I would remove all the copied sections from NumPyDoc and just link to the official guide: https://numpydoc.readthedocs.io/en/latest/format.html Overall I think this is a great addition! But I think use |
|
I abandon this PR, I'm not motivated to continue on this. If someone else wants to document that, I'll be glad. |
GUIDELINES.rst.txt
Outdated
| Docstring | ||
| --------- | ||
|
|
||
| documentation string (docstring) is a string that describes a module, |
GUIDELINES.rst.txt
Outdated
| output. Rather than sacrificing the readability of the docstrings, we | ||
| have written pre-processors to assist Sphinx_ in its task. | ||
|
|
||
| The length of docstring lines should be kept to 75 characters to |
There was a problem hiding this comment.
I think this should be removed. This has fallen out of favor in recent years... Let's move on from the 70s
GUIDELINES.rst.txt
Outdated
| If it is not necessary to specify a keyword argument, use | ||
| ``optional``:: | ||
|
|
||
| x : int, optional |
There was a problem hiding this comment.
I know you all have been adding optional, but I feel like this is the expected default from a keyword argument that has been specified in the signature.
GUIDELINES.rst.txt
Outdated
| demonstrated function, must be explicit. | ||
|
|
||
|
|
||
| cumenting classes |
|
If you want to continue this PR, feel free! :) |
|
Not particularly. I guess I didn't see the point that you abbandoned it too. |
|
Totally into this PR, but there are quite a few changes I'd make. As @hmaarrfk, anything that can be upstreamed, should, by pointing to PEP257 and NumPy's docstring formatting guidelines. I don't have time to do it now but let's leave it open so the work is ready to be picked up by someone. |
|
I'm slowly going through the 1.0 milestone. Removing this from 1.0 as this is more a general documentation improvement and not specific to a release. |
Description
As discussed on the ML, in this PR, we will start to list our guidelines related to our API.
https://mail.python.org/archives/list/scikit-image@python.org/thread/QKGR7YSC34MMXWFWLZNHHL3HJCBSAXN3/
TODO
multichannelparameter handling #2613References