On Thu, Aug 9, 2018 at 7:04 AM, Erik Bray <erik.m.b...@gmail.com> wrote: > On Thu, Aug 9, 2018 at 3:23 PM Simon King <simon.k...@uni-jena.de> wrote: >> >> Hi Eric, >> >> On 2018-08-09, Erik Bray <erik.m.b...@gmail.com> wrote: >> > But it got me thinking: Maybe it would actually be nice if most Sage >> > classes--or at least those inheriting from SageObject, had some >> > version of this .help() method. Although we already do a decent job >> > advertising the ? and ?? syntax, having .help() method is inherently >> > more discoverable (an the help methods in sandpiles even advertise the >> > ? syntax for further details). >> >> I think such method would be fairly useless. >> Reason: If a user seeks help about X by trying X.help() rather than >> help(X) apparently knows about methods, as a corollary knows about >> Python, and as a corollary knows about ? and ??. >> >> While a .help() METHOD seems useless to me, a help() FUNCTION might be >> useful for newbies. Say, help(X) could print a pointer to the "?" syntax >> (so that the newby will soon be a bit less newby) and then print the doc >> string of X. > > Except there is already a help() function built in to Python (and the > default help() is a bit useless compared to our '?' > customizations--it's also confusing that it has different behavior--we > should probably replace the default help() with one that is simply > equivalent to ?).
Our help is customized, but not very much. E.g., sage: help() Welcome to Sage 8.2! To view the Sage tutorial in your web browser, type "tutorial()", and ... However, help on particular things just falls back to Python. > The reason I think a .help() method would be useful is that it IS more > discoverable because it will show up in tab completion--e.g. > `Integer.<tab>`--whereas `?` and `??` do not. (Maybe they should; but > even that is not obvious--e.g. in Ruby "?" is used at the end of > methods that act as predicates and has nothing to do with help). > This sounds like yet more clutter when one does foo.[tab]... It is interesting to google "how to get help python": https://www.google.com/search?q=how+to+get+help+python All the answers are: "use help(foo)". We should thus definitely do what you say and enhance the help top level function. > A newbie doesn't need much experience to find functionality via > tab-completion. It is often taught early on, and even those without > much Sage experience may often discover tab-completion on their own > out of familiarity with other systems (if I were a newbie I'm sure I'd > discover tab-completion on my own just by trying it; `?` not so much). > > In either case, it seems a little silly to have a .help() method on a > small handful of miscellaneous classes, but not others. So I would > either get rid of the miscellaneous .help()s entirely, or add more of > them (and I prefer the latter as it's quite easy to do). I still prefer the former, since: - less clutter - docstrings are in the reference manual, but help is not. - even if you add more, you'll probably still leave 90% of the library untouched; Sage is big! - your suggestion is highly nonstandard; I don't think it is done in numpy, scipy, or any other standard Python library. > > > Additionally, FWIW Sandpile.help() looks like this: > > sage: Sandpile.help() > For detailed help with any method FOO listed below, > enter "Sandpile.FOO?" or enter "S.FOO?" for any Sandpile S. > > all_k_config -- The constant configuration with all values set to > k. > all_k_div -- The divisor with all values set to k. > avalanche_polynomial -- The avalanche polynomial. > betti -- The Betti table for the homogeneous toppling > ideal. > betti_complexes -- The support-complexes with non-trivial homology. > burning_config -- The minimal burning configuration. > burning_script -- A script for the minimal burning configuration. > canonical_divisor -- The canonical divisor. > dict -- A dictionary of dictionaries representing > a directed graph. > genus -- The genus: (# non-loop edges) - (# vertices) + 1. > groebner -- A Groebner basis for the homogeneous toppling > ideal. > group_gens -- A minimal list of generators for the sandpile > group. > group_order -- The size of the sandpile group. > ... and so on ... > > > I rather like how succinct this is compared to > > sage: Sandpile? > Type: LazyImport > String form: <class 'sage.sandpiles.sandpile.Sandpile'> > File: ~/src/sagemath/sage-python3/src/sage/misc/lazy_import.pyx > Docstring: Class for Dhar's abelian sandpile model. > Class docstring: > ... And sage: help(Sandpile) is truly depressing. Remember -- if you google and ask "how to I get help python", you'll be told to use help(...), and if you do that on Sandpile, it's really bad. > > > the rest of which is actually the docs for LazyImport, which is a > known bug. But even without that bug, the '?' is much, much more > verbose. > > -- > 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. -- William (http://wstein.org) -- 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.
