[sage-devel] Re: should "foo?" print TESTS: blocks or omit them?
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.
[sage-devel] Re: should "foo?" print TESTS: blocks or omit them?
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. -- 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.
[sage-devel] Re: should "foo?" print TESTS: blocks or omit them?
[X] 'foo?' should NOT display TESTS blocks. [ ] 'foo?' should display TESTS block. -- Marc -- 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.
Re: [sage-devel] Re: should "foo?" print TESTS: blocks or omit them?
On Fri, 6 Nov 2015, Tom Boothby wrote: A corollary to this is that relevant documentation should not exist in the TESTS block. True. And those edge cases should be documented. Maybe. But something like Graph().is_connected() is easy to check, if the user wants to know if empty graph is defined to be connected. On Fri, 6 Nov 2015, Michael Orlitzky wrote: Write-in candidate: make foo? show the source code at the end of the nicely-formatted docs, and then get rid of foo?? entirely. -1. Too technical, will scare students. (But teachers should show ?? functionality in some lesson, just as a side note. Maybe some on students will be future developers.) -- Jori Mäntysalo
Re: [sage-devel] Re: should "foo?" print TESTS: blocks or omit them?
A corollary to this is that relevant documentation should not exist in the TESTS block. And those edge cases should be documented. If the user wants to know more, foo?? will give them the Only True Documentation, which happens to include the TESTS block. [x] 'foo?' should NOT display TESTS blocks. On Fri, Nov 6, 2015 at 6:11 PM, Travis Scrimshaw wrote: > >> >> [X] 'foo?' should display TESTS block. >> > > I think Thierry's argument about corner cases is a good one. Plus some > docstrings have different input formats in the TESTS block or only have > tests in the TESTS blocks (granted, this is only likely to occur in hidden > functions, but I believe it is currently in the library). > > Best, > Travis > > -- > 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. -- 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.
[sage-devel] Re: should "foo?" print TESTS: blocks or omit them?
> > [X] 'foo?' should display TESTS block. > > I think Thierry's argument about corner cases is a good one. Plus some docstrings have different input formats in the TESTS block or only have tests in the TESTS blocks (granted, this is only likely to occur in hidden functions, but I believe it is currently in the library). Best, Travis -- 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.
