On Mon, Apr 11, 2016 at 03:43:46PM -0700, 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.
It's the code's responsibility to fail gracefully with a useful report
stating which feature/package is required (incidentally, #20382 will
help in this direction).
Personally, as I user, I prefer to be told once about caveats, rather
than being constantly bothered by repeated messages that I'll just end
up skipping visually.
That being said, I see your point that the information should be well
visible, so some Sphinx configuration is in order.
> Even worse if its in the module docstring and not even in the
> method docstring that you are currently looking at.
I don't have a strong opinion here. It's indeed annoying if the user
don't see the information when looking up the documentation of a
single method (e.g. via instrospection). We could potentially hack
something so that the information would be automatically inserted into
each docstring, but that looks brittle.
Not having to implement this feature means less work for me :-)
Cheers,
Nicolas
--
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.
