I agree with this. I'm used to Wikipedia, where See Also, and then 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 On Tue, Jan 10, 2012 at 12:31 AM, Alexey U. Gudchenko <[email protected]> wrote: > 04.01.2012 03:19, Aaron Meurer пишет: >> On Tue, Jan 3, 2012 at 1: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? >> >> 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 >> > > > 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 [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. >>> >> > > > -- > Alexey U. > > -- > 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.
