[sage-devel] Re: Docstring-wide "# optional" markup (#20427) / I am happy

Hi Nicolas, On 2016-04-14, Nicolas M. Thiery wrote: > 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

[sage-devel] Re: Docstring-wide "# optional" markup (#20427) / I am grumpy

Hi Jeroen, On 2016-04-14, Jeroen Demeyer wrote: > 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. I occasionally got errors telling me that Cython does not

[sage-devel] Re: Docstring-wide "# optional" markup (#20427) / I am grumpy

Hi Martin, On 2016-04-13, 'Martin R' via sage-devel wrote: > 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

[sage-devel] Re: Docstring-wide "# optional" markup (#20427) / I am grumpy

On 2016-04-12, 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

[sage-devel] Re: Docstring-wide "# optional" markup (#20427)

On Monday, April 11, 2016 at 11:43:46 PM UTC+1, Volker Braun wrote: > > IMHO thats terrible; When you copy an example it should either work > or say very clear why it is optional. > I disagree. I remember that when my students saw sage documentation for the first time they did not understand

[sage-devel] Re: Docstring-wide "# optional" markup (#20427)

On Mon, Apr 11, 2016 at 03:43:46PM -0700, Volker Braun wrote: >IMHO thats terrible; When you copy 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

[sage-devel] Re: Docstring-wide "# optional" markup (#20427)

Hi Nicolas, On 2016-04-11, Nicolas M. Thiery wrote: > At Sage Days 77, we discussed introducing a docstring-wide markup that > would be equivalent to adding # optional on all the following > doctests. Hooray! I have long been waiting for such a markup, but didn't know

[sage-devel] Re: Docstring-wide "# optional" markup (#20427)

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

[sage-devel] Re: Docstring-wide "# optional" markup (#20427)

IMHO thats terrible; When you copy 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