I think there are two issues: one is how the docstring should be written, and the other is how it should be printed, either via introspection or in the reference manual. So with this proposal, the reference manual could have those blocks nicely delineated, as Nicolas said, to suggest caution when copying and pasting. For introspection, I suppose you could just add "# optional - gap3" at the end of each doctest. There may be better ideas, though.
John On Monday, April 11, 2016 at 3:43:46 PM UTC-7, Volker Braun wrote: > > IMHO thats terrible; When you copy&paste an example it should either work > or say very clear why it is optional. Just having some magic marker > somewhere in the documentation, long before the example starts, is > potentially much more confusing than the visual clutter of repeated magic > comments could ever be. Even worse if its in the module docstring and not > even in the method docstring that you are currently looking at. > > > > > On Tuesday, April 12, 2016 at 12:04:35 AM UTC+2, Nicolas M. Thiéry wrote: >> >> Dear Sage developers, >> >> It's quite common that optional doctests come in batch, typically when >> documenting a method that is only available when a certain feature or >> package is available. Having to mark each and every test line with >> `# optional xxx` is redundant, painful, and harms readability. >> >> At Sage Days 77, we discussed introducing a docstring-wide markup that >> would be equivalent to adding # optional on all the following >> doctests. It could be nice to have it as a Sphinx markup that we could >> possibly highlight nicely (or hide?) in the documentation. Something >> like:: >> >> EXAMPLES:: >> >> sage: ... >> >> .. OPTIONAL:: gap3 >> >> :: >> >> sage: gap3(...) >> sage: gap3(...) >> >> Incidentally, this would be very useful for #11187. >> >> I have posted a preliminary implementation on #20427 [1]. >> >> Feedback welcome! >> >> In particular: do we want to also have a module-wide markup, typically >> when putting the OPTIONAL markup on the module docstring. >> >> Cheers, >> Nicolas >> >> http://trac.sagemath.org/ticket/20427 >> >> -- >> Nicolas M. Thiéry "Isil" <nth...@users.sf.net> >> http://Nicolas.Thiery.name/ >> > -- 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 https://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
