On Tue, Jan 3, 2012 at 12:10 PM, miham <[email protected]> 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? > 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 [email protected]. > To unsubscribe from this group, send email to > [email protected]. > For more options, visit this group at > http://groups.google.com/group/sympy?hl=en. > -- You received this message because you are subscribed to the Google Groups "sympy" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/sympy?hl=en.
