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" <nthi...@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.
