vdumoulin
commented
11 years ago Here are some things worth noting when you work on docstring formatting.
While we follow the Numpy standard for docstrings, we open and close the docstrings differently (see http://deeplearning.net/software/pylearn/v2_planning/API_coding_style.html) :
You do not need to add an extra blank line before the closing quotes of
a multi-line docstring. Also, we ask that the first line of a multi-line
docstring should contain only the opening quotes.For example:
# Good.
"""
This is a multi-line docstring.
Which means it has more than one line.
"""
# Bad.
"""This is a multi-line docstring.
Which means it has more than one line.
"""Also, make sure the colon after the parameter is surrounded by spaces, otherwise it won't be parsed correctly:
# Good
"""
Parameters
----------
a : int
the first value
b : int
the second value
"""
# Bad
"""
Parameters
----------
a: int
the first value
b: int
the second value
"""EDIT: There is an extension installed in our doc called sphinx.ext.todo which you can use to add WRITEMEs to the docstrings:
"""
.. todo::
WRITEME
"""It has the advantage of looking nicer when rendered as HTML than a plain WRITEME, so I suggest we take advantage of it when formatting the docstrings.
nouiz
bouthilx
@memimo set up the numpydoc extension for Sphinx (gh-42), now we have to make sure the documentation generates cleanly (no errors or warning, displayed correctly, etc.).
Also, classes and methods lacking docstrings should have a docstring reading "WRITEME", so we can later grep for them and fill them in.
We will split the repository in:
Numpy standard for docstrings can be found at https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#docstring-standard
If some classes (or functions/methods) already have well-formatted docstrings using another standard, that is OK for the moment, but newly-written or newly-formatted ones should follow the above convention.