Re: [sage-devel] Docstring-wide "# optional" markup (#20427) / I am happy
On Wed, Apr 13, 2016 at 10:56:48AM -0700, mmarco wrote:
>I was thinking of something much deeper, something like:
>@optional('eggs')
>def spam():
>"""
> docstring with the corresponding doctests
>"""
>blah
>And then, several things happen:
> 1. The testing framework ignores the doctests for the function
>`spam`only if the package `eggs` is installed.
> 2. On startup, the function `spam` is defined only if the package
>`eggs` is installed. In particular, tab completion would only show
>it if the package is installed.
> 3. Documentation for the function is only built if the package is
>installed.
Oh, I see. Intriguing indeed. This could also potentially take care
automatically of raising the "required feature/package" message upon
calling the method, so that it's not necessary anymore to handle it
inside the code.
I second Martin's comment that it's good for feature discovery to keep
the method in the documentation and tab completion. Not sure whether
we can customize tab completion to have two levels of coloring
(incidentally, such a feature could be useful for e.g. abstract
methods).
So now we have (at least) the following proposals:
1. a decorator applying to the full docstring
2. a markup applying to everything below in the docstring (e.g. .. OPTIONAL::
gap)
3. a markup applying to a single block of code
4. just the current line-by-line markup
Not sure how to choose. At this point I lean more toward a markup: the
additional features of the decorator are only tentative at this point,
and I have the impression that the decorator requires more
infrastructure and is less flexible.
Simon: would you have a sample file of yours where you could
experiment with markup's 2. or 3 (even if they don't do anything for
now) and report which seems more practical as a documentation writer?
Cheers,
Nicolas
PS1: thank you everyone for all the ideas and for the peaceful
discussion; it's a pleasure to participate.
PS2: I am on vacations for the next 10 days. Feel free to take over
the ticket in the mean time; adapting it to 3. should be
straightforward. What will remain is to customize Sphinx to highlight
the markup in the documentation.
--
Nicolas M. Thiéry "Isil"
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.
Re: [sage-devel] Docstring-wide "# optional" markup (#20427) / I am grumpy
That would be awesome! In fact, within emacs (sage-mode) I also get all the underscored methods, which I don't like at all. I should ask about that... Am Mittwoch, 13. April 2016 23:12:37 UTC+2 schrieb mmarco: > > That's a valid point. Maybe there is a middle option that could combine > the best of both worlds: is it possible to tweak tab-completion in such a > way that certain functions are printed in different colors? > > El miércoles, 13 de abril de 2016, 22:07:28 (UTC+2), Martin R escribió: >> >> A thought: it might in fact be a feature that tab completion *does* show >> methods which only work with optional packages. I usually try >> tab-completion first. I won't mind at all hitting an error message "Please >> install the optional package Foo" if it saves me an hour of internet >> search, fiddling or even programming. >> >> Martin >> > -- 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.
Re: [sage-devel] Docstring-wide "# optional" markup (#20427) / I am grumpy
On 2016-04-14 00:00, Simon King wrote: If I understand correctly, such a decorator would not work in Cython code. Why not? Cython supports decorators. -- 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.
Re: [sage-devel] Docstring-wide "# optional" markup (#20427)
Then "OPTIONAL - foo" gets the same status with "EXAMPLES" (or "INPUT", "OUTPUT", etc). This conveys a misconception since "OPTIONAL" does not mean anything with the method or function that this docstring is attached to. I prefer Dima's suggestion or some variant of that. -- 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.
Re: [sage-devel] Docstring-wide "# optional" markup (#20427)
I think that having an optional Sphinx block is a good idea. Perhaps it could be colored differently in the html documentation (like WARNING blocks are)? When printing on the command line, I think we're just used to the #optional tag. It's unclear to me whether the #optional tag or an OPTIONAL block is more confusing/more likely to be missed for a new user. I agree with Volker and Jeroen that a module level optional tag is not a good idea, since it's not localized. David On Wed, Apr 13, 2016 at 5:58 PM, Simon King wrote: > > Am Mittwoch, 13. April 2016 19:22:12 UTC+2 schrieb Volker Braun: >> >> Or just call the block OPTIONAL, so that >> >> EXAMPLES:: >> >> sage: bar() # optional - foo >> sage: baz() # optional - foo >> >> is equivalent to >> >> OPTIONAL - foo:: >> >> sage: bar() >> sage: baz() >> > > I like that proposal. > > -- > 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. > -- 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.
Re: [sage-devel] Docstring-wide "# optional" markup (#20427) / I am grumpy
Hi Marco,
Am Mittwoch, 13. April 2016 19:56:48 UTC+2 schrieb mmarco:
>
>
> @optional('eggs')
> def spam():
> """
>docstring with the corresponding doctests
> """
> blah
>
>
If I understand correctly, such a decorator would not work in Cython code.
Best regards,
Simon
--
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.
Re: [sage-devel] Docstring-wide "# optional" markup (#20427)
Am Mittwoch, 13. April 2016 19:22:12 UTC+2 schrieb Volker Braun: > > Or just call the block OPTIONAL, so that > > EXAMPLES:: > > sage: bar() # optional - foo > sage: baz() # optional - foo > > is equivalent to > > OPTIONAL - foo:: > > sage: bar() > sage: baz() > I like that proposal. -- 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.
Re: [sage-devel] Docstring-wide "# optional" markup (#20427) / I am grumpy
That's a valid point. Maybe there is a middle option that could combine the best of both worlds: is it possible to tweak tab-completion in such a way that certain functions are printed in different colors? El miércoles, 13 de abril de 2016, 22:07:28 (UTC+2), Martin R escribió: > > A thought: it might in fact be a feature that tab completion *does* show > methods which only work with optional packages. I usually try > tab-completion first. I won't mind at all hitting an error message "Please > install the optional package Foo" if it saves me an hour of internet > search, fiddling or even programming. > > Martin > -- 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.
Re: [sage-devel] Docstring-wide "# optional" markup (#20427) / I am grumpy
A thought: it might in fact be a feature that tab completion *does* show methods which only work with optional packages. I usually try tab-completion first. I won't mind at all hitting an error message "Please install the optional package Foo" if it saves me an hour of internet search, fiddling or even programming. Martin -- 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.
Re: [sage-devel] Docstring-wide "# optional" markup (#20427) / I am grumpy
On Wed, 13 Apr 2016, mmarco wrote:
@optional('eggs')
And then, several things happen:
2. On startup, the function `spam` is defined only if the package `eggs` is
installed. In particular, tab completion would only show it if the
package is installed.
That would be extremely nice. But we have also options like
algorithm='bliss'. So in ideal solution installing a package would even
change behaviour (and documentation) of existing functions!
And yes, it would need rethinking structure from scratch.
--
Jori Mäntysalo
Re: [sage-devel] Docstring-wide "# optional" markup (#20427) / I am grumpy
I was thinking of something much deeper, something like:
@optional('eggs')
def spam():
"""
docstring with the corresponding doctests
"""
blah
And then, several things happen:
1. The testing framework ignores the doctests for the function
`spam`only if the package `eggs` is installed.
2. On startup, the function `spam` is defined only if the package `eggs`
is installed. In particular, tab completion would only show it if the
package is installed.
3. Documentation for the function is only built if the package is
installed.
I know this goes way beyond what you proposed, but on the other hand I
think it makes sense to distinguish if a package is installed or not at
more levels than just the doctesting.
El miércoles, 13 de abril de 2016, 19:01:33 (UTC+2), Nicolas M. Thiéry
escribió:
>
>Hi Miguel,
>
> On Wed, Apr 13, 2016 at 03:05:56AM -0700, mmarco wrote:
> >Sorry if I sounded rude or disrispectful, It wasn't my intention at
> >all.
>
> No worry, I know :-)
>
> >Let me try to redeem myself by proposing some constructive proposal:
>
> Thanks!
>
> >what about a function/method level mark (be it a decorator or a
> >comment)?
>
> The current implementation in #20427 applies only to the current
> method (in fact only to the doctests after the markup). Up to syntax,
> is this what you have in mind? Any suggestion of better syntax?
>
> >It could have more benefits than just treating correctly the
> >doctests. It could also help, for instance, creating a
> >documentation section automatically, or even not exposing the
> >function at all if the corresponding package is not installed.
>
> Yes! Practice would tell us which of those features we would want to
> implement.
>
> >Of course, this idea has many drawbacks: the optional functionality
> >might deppend only on certain parameters (e.g. the 'algorithm'
> >keyword)... but maybe they could be worked out.
>
> Indeed; anyway when a finer granularity is required, the usual #
> optional works just fine.
>
> Cheers,
> Nicolas
>
> [1] http://trac.sagemath.org/ticket/20427
> --
> Nicolas M. Thiéry "Isil" >
> 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.
Re: [sage-devel] Docstring-wide "# optional" markup (#20427)
On Tuesday, April 12, 2016 at 1:48:17 PM UTC+2, Dima Pasechnik wrote: > perhaps a meaningful compromise would be test-wise #optional tags, per > test/example or per test/example block > Or just call the block OPTIONAL, so that EXAMPLES:: sage: bar() # optional - foo sage: baz() # optional - foo is equivalent to OPTIONAL - foo:: sage: bar() sage: baz() -- 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.
Re: [sage-devel] Docstring-wide "# optional" markup (#20427) / I am grumpy
Hi Miguel, On Wed, Apr 13, 2016 at 03:05:56AM -0700, mmarco wrote: >Sorry if I sounded rude or disrispectful, It wasn't my intention at >all. No worry, I know :-) >Let me try to redeem myself by proposing some constructive proposal: Thanks! >what about a function/method level mark (be it a decorator or a >comment)? The current implementation in #20427 applies only to the current method (in fact only to the doctests after the markup). Up to syntax, is this what you have in mind? Any suggestion of better syntax? >It could have more benefits than just treating correctly the >doctests. It could also help, for instance, creating a >documentation section automatically, or even not exposing the >function at all if the corresponding package is not installed. Yes! Practice would tell us which of those features we would want to implement. >Of course, this idea has many drawbacks: the optional functionality >might deppend only on certain parameters (e.g. the 'algorithm' >keyword)... but maybe they could be worked out. Indeed; anyway when a finer granularity is required, the usual # optional works just fine. Cheers, Nicolas [1] http://trac.sagemath.org/ticket/20427 -- Nicolas M. Thiéry "Isil" 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.
Re: [sage-devel] Docstring-wide "# optional" markup (#20427) / I am grumpy
Sorry if I sounded rude or disrispectful, It wasn't my intention at all. Let me try to redeem myself by proposing some constructive proposal: what about a function/method level mark (be it a decorator or a comment)? It could have more benefits than just treating correctly the doctests. It could also help, for instance, creating a documentation section automatically, or even not exposing the function at all if the corresponding package is not installed. Of course, this idea has many drawbacks: the optional functionality might deppend only on certain parameters (e.g. the 'algorithm' keyword)... but maybe they could be worked out. El martes, 12 de abril de 2016, 23:52:18 (UTC+2), Nicolas M. Thiéry escribió: > > On Tue, Apr 12, 2016 at 02:03:15AM -0700, mmarco wrote: > >I agree with Volker here. If the problem is that writing a > ># optional blah > > at the end of each line that starts with > >sage: > > maybe limited to a certain portion of your file, that sounds like > the > >kind of thing you could easily do with some simple plugin for your > >favourite text editor. Or a regex substitution. > > Don't worry, I know how to use my editor for automated tasks. > Don't worry, I know how to use my editor for automated tasks. > Don't worry, I know how to use my editor for automated tasks. > Don't worry, I know how to use my editor for automated tasks. > Don't worry, I know how to use my editor for automated tasks. > Don't worry, I know how to use my editor for automated tasks. > Don't worry, I know how to use my editor for automated tasks. > Don't worry, I know how to use my editor for automated tasks. > Don't worry, I know how to use my editor for automated tasks. > Don't worry, I know how to use my editor for automated tasks. > Don't worry, I know how to use my editor for automated tasks. > > Sorry, I could not resist. I know, I tend to be picky and grumpy. > > It's not specifically about this particular e-mail. And I have no > problem with suggestions for improvements being discussed and not > being accepted; on the contrary the diversity of perspectives is a > strength of this community. > > On the other hand I am frustrated with the tone of sage-devel these > days. I would really appreciate if e-mails would acknowledge others > efforts; something like "thanks for the suggestion and for > investigating how to implement it". > > I am not going to quit sage-devel just for that, but others will (and > have). > > Cheers, > Nicolas > -- > Nicolas M. Thiéry "Isil" > > 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.
Re: [sage-devel] Docstring-wide "# optional" markup (#20427) / I am grumpy
On Tue, Apr 12, 2016 at 09:14:44PM +0200, Nicolas M. Thiery wrote: > On the other hand I am frustrated with the tone of sage-devel these > days. I would really appreciate if e-mails would acknowledge others > efforts; something like "thanks for the suggestion and for > investigating how to implement it". Oops, and this applies to me in the first place: Thanks everyone for your comments! Cheers, Nicolas -- Nicolas M. Thiéry "Isil" 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.
Re: [sage-devel] Docstring-wide "# optional" markup (#20427) / I am grumpy
On Tue, Apr 12, 2016 at 02:03:15AM -0700, mmarco wrote: >I agree with Volker here. If the problem is that writing a ># optional blah > at the end of each line that starts with >sage: > maybe limited to a certain portion of your file, that sounds like the >kind of thing you could easily do with some simple plugin for your >favourite text editor. Or a regex substitution. Don't worry, I know how to use my editor for automated tasks. Don't worry, I know how to use my editor for automated tasks. Don't worry, I know how to use my editor for automated tasks. Don't worry, I know how to use my editor for automated tasks. Don't worry, I know how to use my editor for automated tasks. Don't worry, I know how to use my editor for automated tasks. Don't worry, I know how to use my editor for automated tasks. Don't worry, I know how to use my editor for automated tasks. Don't worry, I know how to use my editor for automated tasks. Don't worry, I know how to use my editor for automated tasks. Don't worry, I know how to use my editor for automated tasks. Sorry, I could not resist. I know, I tend to be picky and grumpy. It's not specifically about this particular e-mail. And I have no problem with suggestions for improvements being discussed and not being accepted; on the contrary the diversity of perspectives is a strength of this community. On the other hand I am frustrated with the tone of sage-devel these days. I would really appreciate if e-mails would acknowledge others efforts; something like "thanks for the suggestion and for investigating how to implement it". I am not going to quit sage-devel just for that, but others will (and have). Cheers, Nicolas -- Nicolas M. Thiéry "Isil" 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.
Re: [sage-devel] Docstring-wide "# optional" markup (#20427)
On Tuesday, April 12, 2016 at 8:37:53 AM UTC+1, Jeroen Demeyer wrote: > > On 2016-04-12 00:04, Nicolas M. Thiery 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. > > Let me add something here: often, not *every* test requires the optional > package. It can happen that basic things like initializing and printing > some object does not need any optional functionality. In this case, it > is good to always run these tests. And having the module-level "# > optional" goes against this. > perhaps a meaningful compromise would be test-wise #optional tags, per test/example or per test/example block, i.e. TESTS: blah :: #optional - foo bah :: # nothing optional needed here EXAMPLES :: #optional - foo, bar -- 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.
Re: [sage-devel] Docstring-wide "# optional" markup (#20427)
I agree with Volker here. If the problem is that writing a # optional blah at the end of each line that starts with sage: maybe limited to a certain portion of your file, that sounds like the kind of thing you could easily do with some simple plugin for your favourite text editor. Or a regex substitution. -- 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.
Re: [sage-devel] Docstring-wide "# optional" markup (#20427)
On 2016-04-12 00:04, Nicolas M. Thiery 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. Let me add something here: often, not *every* test requires the optional package. It can happen that basic things like initializing and printing some object does not need any optional functionality. In this case, it is good to always run these tests. And having the module-level "# optional" goes against this. -- 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.
Re: [sage-devel] Docstring-wide "# optional" markup (#20427)
On 2016-04-12 00:04, Nicolas M. Thiery 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. I agree with Volker here: I don't think it's painful or harms readability. It's very explicit, which is good. -- 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.
[sage-devel] Docstring-wide "# optional" markup (#20427)
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" 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.
