On Saturday, November 7, 2015 at 2:01:17 AM UTC-8, Volker Braun wrote: > > I don't really care about whether to display TESTS:: or not, but we really > should have a proper parser for our docstring style. This ticket adds yet > another regex hack. E.g. sphinxcontrib-napoleon is an example for how it is > done correctly: >
> * Nicer typeset output since the docbuilder has semantic knowledge, e.g. > http://bwanamarko.alwaysdata.net/napoleon/format_exception.html > > * Less ambiguity (single or double "--"?) > > * Fewer potential for mistakes as you don't have to do the formatting by > hand, no standard double backticks that always have to be put at a certain > place etc... > > * Potential for automatted testing: If you can parse the documented > argspec then you can compare with the actual argspec > > A slightly related question, do we really need a special Sage docstring > style. Its just unnecessary. Just use a standard that already has tooling > support (like sphinx-napoleon), or at least a minor extension thereof. Lots > of projects use Google style, e.g. Khan academy. > I think it is several years too late for this sort of comment. Are we going to rewrite all of our docstrings to conform to a new style? Sounds like a nightmare. Modifying napoleon to deal with Sage's docstring style (and also allowing Google style docstrings, for example) sounds much more practical. -- John -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To post to this group, send email to sage-devel@googlegroups.com. Visit this group at http://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.