Open rwst opened 9 years ago
That's interesting, because here exactly this constant is used to show how awesome the interactive help is! So something is messed up.
This appears to be broken for most constants declared in sage/symbolic/constants.py
with the exception of e
.
I would expect that Expression
would have a custom _sage_doc
function that would reroute the help request to the appropriate class, but no such function seems to exist, or to ever have existed. If someone indicates how this should work, I'll be glad to try to fix it.
On a not entirely unrelated note: The format of the help has changed somewhat from what is written in the tutorial.
On a not entirely unrelated note: The format of the help has changed somewhat from what is written in the tutorial.
Can you be more specific?
Replying to @kcrisman:
On a not entirely unrelated note: The format of the help has changed somewhat from what is written in the tutorial.
Can you be more specific?
I thought I had answered this a while ago. Obviously I got distracted.
The tutorial help for tan (gotten locally from file:///Users/davideinstein/projects/sage/src/doc/output/html/en/tutorial/tour_help.html
looks like:
sage: tan?
Type: <class 'sage.calculus.calculus.Function_tan'>
Definition: tan( [noargspec] )
Docstring:
The tangent function
EXAMPLES:
sage: tan(pi)
0
sage: tan(3.1415)
-0.0000926535900581913
sage: tan(3.1415/4)
0.999953674278156
sage: tan(pi/4)
1
sage: tan(1/2)
tan(1/2)
sage: RR(tan(1/2))
0.546302489843790
If I run tan?
in sage 6.7 I get
Type: Function_tan
String form: tan
File: ~/projects/sage/local/lib/python2.7/site-packages/sage/functions/trig.py
Docstring:
The tangent function.
EXAMPLES:
sage: tan(pi)
0
sage: tan(3.1415)
-0.0000926535900581913
sage: tan(3.1415/4)
0.999953674278156
sage: tan(pi/4)
1
sage: tan(1/2)
tan(1/2)
sage: RR(tan(1/2))
0.546302489843790
We can prevent evaluation using the "hold" parameter:
sage: tan(pi/4,hold=True)
tan(1/4*pi)
To then evaluate again, we currently must use Maxima via
"sage.symbolic.expression.Expression.simplify()":
sage: a = tan(pi/4,hold=True); a.simplify()
1
TESTS:
sage: conjugate(tan(x))
tan(conjugate(x))
sage: tan(complex(1,1)) # rel tol 1e-15
(0.2717525853195118+1.0839233273386946j)
Init docstring:
The tangent function.
EXAMPLES:
sage: tan(pi)
0
sage: tan(3.1415)
-0.0000926535900581913
sage: tan(3.1415/4)
0.999953674278156
sage: tan(pi/4)
1
sage: tan(1/2)
tan(1/2)
sage: RR(tan(1/2))
0.546302489843790
We can prevent evaluation using the "hold" parameter:
sage: tan(pi/4,hold=True)
tan(1/4*pi)
To then evaluate again, we currently must use Maxima via
"sage.symbolic.expression.Expression.simplify()":
sage: a = tan(pi/4,hold=True); a.simplify()
1
TESTS:
sage: conjugate(tan(x))
tan(conjugate(x))
sage: tan(complex(1,1)) # rel tol 1e-15
(0.2717525853195118+1.0839233273386946j)
Call docstring:
Wrapper around "BuiltinFunction.__call__()" which converts Python
>>``<<int``s which are returned by Ginac to Sage Integers.
This is needed to fix http://trac.sagemath.org/10133, where Ginac
evaluates "sin(0)" to the Python int "0":
sage: from sage.symbolic.function import BuiltinFunction
sage: out = BuiltinFunction.__call__(sin, 0)
sage: out, parent(out)
(0, <type 'int'>)
With this wrapper we have:
sage: out = sin(0)
sage: out, parent(out)
(0, Integer Ring)
However, if all inputs are Python types, we do not convert:
sage: out = sin(int(0))
sage: (out, parent(out))
(0, <type 'int'>)
sage: out = arctan2(int(0), float(1))
sage: (out, parent(out))
(0, <type 'int'>)
sage: out = arctan2(int(0), RR(1))
sage: (out, parent(out))
(0, Integer Ring)
The Type:
is shorter. The module information is now in the new File:
line.
The Definition:
has been kidnapped by aliens, possibly replaced by the less informative String Form:
.
The Init Docstring
and Call Docstring
have been added.
Replying to @deinst:
This appears to be broken for most constants declared in
sage/symbolic/constants.py
with the exception ofe
.
This works because e
is not a PyObject
embedded in an Expression
like pi
(where pi.pyobject()
returns that object). e
has its own class, and so its own docstring. e.is_constant()
returns True
because is_constant()
just checks that there are no variables present.
I would expect that
Expression
would have a custom_sage_doc
function that would reroute the help request to the appropriate class, but no such function seems to exist, or to ever have existed. If someone indicates how this should work, I'll be glad to try to fix it.
Well, _sage_doc()_
apparently(?) has nothing to do with what IPython prints when appending ?
to an object (same as giving the %pdoc
magic). This is some other help mechanism.
Okay, there is now sage.docs.instancedoc
. This will work.
Branch: u/rws/fix_log2_help
Author: Ralf Stephan
The uninformative docstring from the Expression
class that follows the constant docstring will be improved in another ticket.
Please review.
New commits:
d080e9e | 18077: fix docstring printing of constants |
What does the following sentence mean:
Instances of constants are usually embedded as ``PyObject`` in
a symbolic expression.
Can you move the doctest to the _instancedoc_
method? It seems like it would best fit there. I would also want to see a doctest for the __doc__
of an Expression
which is not a constant, something like (sin(x) + 1).__doc__
I'm not convinced by the except AttributeError
. It seems that every object has a __doc__
, but it could be empty. So instead of the AttributeError
, it would be better to do something like:
doc = self.pyobject().__doc__
if doc:
return doc
return type(self).__doc__ # Isn't self.__doc__ an infinite recursion?
Reviewer: Jeroen Demeyer
Replying to @jdemeyer:
What does the following sentence mean:
Instances of constants are usually embedded as ``PyObject`` in a symbolic expression.
Does this make more sense? Instances of constants are usually embedded in a symbolic expression.
I'll also move the orphaned docstring for I
to the file where it is defined, because at the moment the reference manual associates it with the wrong object.
Changed branch from u/rws/fix_log2_help to u/rws/18077
Note that I also improved docstrings for the class, init, and call slots. Suggestions welcome.
New commits:
6103879 | 18077: fix docstring printing of constants |
Replying to @rwst:
I'll also move the orphaned docstring for
I
to the file where it is defined, because at the moment the reference manual associates it with the wrong object.
You can just remove that docstring. For some reason, it is an identical copy of a docstring in init_pynac_I()
.
Improved branch uploaded.
Branch pushed to git repo; I updated commit sha1. New commits:
281eb93 | remove duplicate docstring |
Please rebase to latest master.
I'm also wondering whether this could help with #26492 and/or #26297
Other constants give more or less specific help but
This confused me because I first thought I had found the Sage binary log function.
Component: documentation
Author: Ralf Stephan
Branch/Commit: u/rws/18077 @
281eb93
Reviewer: Jeroen Demeyer
Issue created by migration from https://trac.sagemath.org/ticket/18077