A quick poll about docstrings
miham
The effort has been pretty successful (more info: [1]), but some
questions remain open, so I thought it might be worth asking what the
community thinks. Here are the questions:
1. Should the summary be on the same line as the opening quotes ("""),
or on the next line?
2. Should there be a blank line after every section header?
3. Should the order of sections be predefined or left to the
discretion of the developers.
Here are my preferences:
1. I would put the summary on the same line as the opening quotes. I
use vim folding [3], so when i open a python file, i see only function/
class definitions and the first line of docstrings (because they are
the first line of the new indentation level). Thus i can get quick
overview of a file.
2. I would put a blank line after every section header, because it
makes it more readable.
3. I think that predefined section order is a good thing, because the
consistency makes information easier to find (you know where to look
for it). SciPy/NumPy section order [2] could be used.
Luckily none of these conventions would make developer's work any
harder. Quite the contrary - it is easier to do the right thing if you
know what the right thing is.
[1] https://github.com/sympy/sympy/wiki/Writing-documentation
[2] https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
[3] http://vim.wikia.com/wiki/Folding
Ondřej Čertík
> Lately there has been some efforts to standardize docstrings in SymPy.
> The effort has been pretty successful (more info: [1]), but some
> questions remain open, so I thought it might be worth asking what the
> community thinks. Here are the questions:
>
> 1. Should the summary be on the same line as the opening quotes ("""),
> or on the next line?
> 2. Should there be a blank line after every section header?
What do you mean by "section header"? Things like "See Also" and "Examples"?
> 3. Should the order of sections be predefined or left to the
> discretion of the developers.
>
> Here are my preferences:
>
> 1. I would put the summary on the same line as the opening quotes. I
> use vim folding [3], so when i open a python file, i see only function/
> class definitions and the first line of docstrings (because they are
> the first line of the new indentation level). Thus i can get quick
> overview of a file.
I personally like to put the summary on the next line, but I admit
that's because
I am used to do it like that. I am open to the other convention too. So +0.
> 2. I would put a blank line after every section header, because it
> makes it more readable.
+1
> 3. I think that predefined section order is a good thing, because the
> consistency makes information easier to find (you know where to look
> for it). SciPy/NumPy section order [2] could be used.
+1 to try to make it consistent.
Ondrej
>
> Luckily none of these conventions would make developer's work any
> harder. Quite the contrary - it is easier to do the right thing if you
> know what the right thing is.
>
> [1] https://github.com/sympy/sympy/wiki/Writing-documentation
> [2] https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
> [3] http://vim.wikia.com/wiki/Folding
>
> --
> You received this message because you are subscribed to the Google Groups "sympy" group.
> To post to this group, send email to sy...@googlegroups.com.
> To unsubscribe from this group, send email to sympy+un...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/sympy?hl=en.
>
Aaron Meurer
> Lately there has been some efforts to standardize docstrings in SymPy.
> The effort has been pretty successful (more info: [1]), but some
> questions remain open, so I thought it might be worth asking what the
> community thinks. Here are the questions:
>
> 1. Should the summary be on the same line as the opening quotes ("""),
> or on the next line?
I don't like this, but I don't think we should require either way
(docstrings should be consistant within the same module, but that's
it). Personally, the off center just makes things look bad, and
anyway, you lose three characters for your "one-line" summary if you
do this.
vim is pretty extensible, and I've found the extension language to be
very easy to use. It's probably possible to extend the folding to
always show the first line with some plugin or maybe even a few lines
in your .vimrc.
> 2. Should there be a blank line after every section header?
I agree. This greatly improves readability.
> 3. Should the order of sections be predefined or left to the
> discretion of the developers.
I don't care about this. We already apparently have to require that
only specific words be header for the numpy doc extension to work
(though I think this can be fixed).
I would try to stray away from having too many fixed requirement for
the formatting of docstrings, as I think it's better to leave it up to
the writer to use his best judgement for what he wants to say. Also,
not all docstrings are equal because not all functions are equal. For
example, some docstrings just document what the function/class is
(most things in the functions module are like this). Others have a
some kind of discussion about various things (see e.g., the simplify()
docstring). Of course, we should require that each docstring be
formatted in a way that works well with Sphinx.
Aaron Meurer
>
> Here are my preferences:
>
> 1. I would put the summary on the same line as the opening quotes. I
> use vim folding [3], so when i open a python file, i see only function/
> class definitions and the first line of docstrings (because they are
> the first line of the new indentation level). Thus i can get quick
> overview of a file.
> 2. I would put a blank line after every section header, because it
> makes it more readable.
> 3. I think that predefined section order is a good thing, because the
> consistency makes information easier to find (you know where to look
> for it). SciPy/NumPy section order [2] could be used.
>
> Luckily none of these conventions would make developer's work any
> harder. Quite the contrary - it is easier to do the right thing if you
> know what the right thing is.
>
> [1] https://github.com/sympy/sympy/wiki/Writing-documentation
> [2] https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
> [3] http://vim.wikia.com/wiki/Folding
>
Chris Smith
On Tue, Jan 3, 2012 at 1:10 PM, miham <tlor...@gmail.com> wrote:
> Lately there has been some efforts to standardize docstrings in SymPy.
> The effort has been pretty successful (more info: [1]), but some
> questions remain open, so I thought it might be worth asking what the
> community thinks. Here are the questions:
>
> 1. Should the summary be on the same line as the opening quotes ("""),
> or on the next line?
Alexey U. Gudchenko
Regarding the order.
Taking into account that this question is raised in pull request 938,
taking into acount that the section order of SciPy/NumPy [2] is not a
single etalone, (e.g. Sage's section order has 'Examples' upper, and
'References' below.)
And that I totally agreed with Aaron's arguments, I vote to have *not* a
strict section order. Only as recommendation or as an example.
P.S.
And about the example of order, now in [1] it is like
Short summary
Deprecation warning
Extended summary
Parameters
Returns
Other parameters
Raises
See Also
Notes
References
Examples
For myself only, I tend to put "Examples" upper, and "References" below.
And "See Also" after the examples. I try to explain it, that I split it
in my mind as:
# Text description
Short summary
Deprecation warning
Extended summary
# Technical information
Parameters
Returns
Other parameters
Raises
# Use cases: look here, to see, try it or to see the other things.
Examples
See Also
# Additional text info.
# Read it after the above things are read, so it is clear
# what are the notes about.
# And only if you interested in it.
Notes
# Go away to the library only,
# when the above text is not sufficient.
References
[1] https://github.com/sympy/sympy/wiki/Writing-documentation
[2] https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
[3] http://vim.wikia.com/wiki/Folding
[4]
http://www.sagemath.org/doc/developer/conventions.html#docstring-markup-with-rest-and-sphinx
>>
>> Here are my preferences:
>>
>> 1. I would put the summary on the same line as the opening quotes. I
>> use vim folding [3], so when i open a python file, i see only function/
>> class definitions and the first line of docstrings (because they are
>> the first line of the new indentation level). Thus i can get quick
>> overview of a file.
>> 2. I would put a blank line after every section header, because it
>> makes it more readable.
>> 3. I think that predefined section order is a good thing, because the
>> consistency makes information easier to find (you know where to look
>> for it). SciPy/NumPy section order [2] could be used.
>>
>> Luckily none of these conventions would make developer's work any
>> harder. Quite the contrary - it is easier to do the right thing if you
>> know what the right thing is.
>>
>> [1] https://github.com/sympy/sympy/wiki/Writing-documentation
>> [2] https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
>> [3] http://vim.wikia.com/wiki/Folding
>>
>> --
>> You received this message because you are subscribed to the Google Groups "sympy" group.
>> To post to this group, send email to sy...@googlegroups.com.
>> To unsubscribe from this group, send email to sympy+un...@googlegroups.com.
>> For more options, visit this group at http://groups.google.com/group/sympy?hl=en.
>>
>
--
Alexey U.
Chris Smith
For myself only, I tend to put "Examples" upper, and "References" below.
And "See Also" after the examples. I try to explain it, that I split it
in my mind as:
# Text description
Short summary
Deprecation warning
Extended summary
# Technical information
Parameters
Returns
Other parameters
Raises
# Use cases: look here, to see, try it or to see the other things.
Examples
See Also
# Additional text info.
# Read it after the above things are read, so it is clear
# what are the notes about.
# And only if you interested in it.
Notes
# Go away to the library only,
# when the above text is not sufficient.
Joachim Durchholz
> And that I totally agreed with Aaron's arguments, I vote to have *not* a
> strict section order. Only as recommendation or as an example.
+1
There's always the special case where a different order makes the doc
much more readable.
b.ballk...@gmail.com
----------
Sent via Nokia Email
+1
--
Aaron Meurer
References are at the very end.
And I think there's a consensus to make it just a suggestion, and not
a requirement. I'll fix the wording on the wiki page to this effect.
Aaron Meurer