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.

Reply via email to