Opened 4 years ago
Last modified 9 months ago
#12891 needs_info enhancement
Invite for contributing a doctest, if a user reads an untested function or method
Reported by: | SimonKing | Owned by: | was |
---|---|---|---|
Priority: | major | Milestone: | sage-6.4 |
Component: | user interface | Keywords: | documentation untested |
Cc: | drkirkby | Merged in: | |
Authors: | Reviewers: | ||
Report Upstream: | N/A | Work issues: | |
Branch: | Commit: | ||
Dependencies: | Stopgaps: |
Description (last modified by chapoton)
The aim of this ticket is to encourage users to (start to) contribute doctests to Sage, so that we can more easily achieve the goal of full doctest coverage.
On sage-devel, Johan Grönqvist suggested to add a message when a function is called that has no doctest. The problem is that that would massively affect the performance.
I suggested a modification of that idea: When the user reads the documentation of an untested function (or method) either in the notebook or the command line interface, s/he should be invited to contribute a test, such as
sage: def my_function(a,b): ....: """ ....: some docs, but no test ....: """ ....: return a+b ....: sage: my_function? Type:function Base Class:<type 'function'> String Form:<function my_function at 0x7309938> Namespace:Interactive Loaded File:/mnt/local/king/SAGE/stable/sage-5.0.beta13/devel/sage-main/<ipython console> Source File:/mnt/local/king/SAGE/stable/sage-5.0.beta13/devel/sage-main/<ipython console> Definition:my_function(a, b) Docstring: #### # my_function appears to be untested. # The Sage community would appreciate if someone (e.g., you) # added a test to the documentation. #### some docs, but no test
Or perhaps only add the message if the function's module starts with 'sage'.
Reading the documentation is certainly not critical for performance. I thought it could be implemented in sage/misc/sagedoc.py or sage/misc/sageinspect.py. Unfortunately, this only holds for the ipython interface of Sage. The notebook seems to use stuff in sagenb/misc/support.py and sagenb/misc/sageinspect.py (which is an outdated copy of sage/misc/sageinspect.py!).
Change History (13)
comment:1 Changed 4 years ago by SimonKing
- Description modified (diff)
comment:2 Changed 4 years ago by drkirkby
- Cc drkirkby added
comment:3 follow-up: ↓ 4 Changed 4 years ago by drkirkby
comment:4 in reply to: ↑ 3 Changed 4 years ago by SimonKing
- Type changed from PLEASE CHANGE to enhancement
Replying to drkirkby:
I'm guessing this will be a sort of meta-ticket, where you open another ticket for an undocumented function, and provide a link here. Hopefully then writing the doctest on the other ticket. Is that what you had in mind?
Not at all. As the ticket description says: The aim is to change the behaviour of obj? in Notebook and ipython interface (I am afraid both needs to be done) so that people trying to read the documentation of obj are encouraged to contribute a doctest (of course only if such doctest is missing).
In other words, this is not a (meta-)ticket about doctests but a ticket about a potential approach to get people to start contributing to sage by writing doctests (this is why I chose the component "user interface", not "doctest").
comment:5 follow-up: ↓ 6 Changed 4 years ago by jhpalmieri
By the way, would it make sense to eliminate the Sage version of sageinspect.py, and just use the version from sagenb all the time? Since sagenb is part of Sage, we would always have access to this file, but it still allows sagenb to be a standalone project. (This requires updating the version of sageinspect.py currently in sagenb, of course.)
comment:6 in reply to: ↑ 5 Changed 4 years ago by SimonKing
Replying to jhpalmieri:
By the way, would it make sense to eliminate the Sage version of sageinspect.py, and just use the version from sagenb all the time? Since sagenb is part of Sage, we would always have access to this file, but it still allows sagenb to be a standalone project. (This requires updating the version of sageinspect.py currently in sagenb, of course.)
From my perspective, it does not make sense that any version of sageinspect is in sagenb, if the sage notebook wants to pretend to be standalone.
sageinspect is supposed to know how to find sources in the SAGE_ROOT/devel/sage/ repository, but I don't think that the notebook should try to find files in SAGE_ROOT/devel/sage/ if it is used in a project that has nothing to do with Sage.
Off topic:
A better solution for the notebook as a standalone project would be to create a hook for the relevant functionality: The relevant functions are supposed to return the doc of a given object or to find the source of a given object or to determine the arguments of a function.
In other words, there should be a module sagenb.inspect containing placeholder functions such as get_doc and get_sourcelines (perhaps defaulting to Python's inspect.getdoc and inspect.getsourcelines), and the notebook should entirely rely on these functions. Now, if one wants to use the standalone notebook for Sage, then one has to do
sagenb.inspect.getdoc = sage.misc.sageinspect.sage_getdoc sagenb.inspect.getsourcelines = sage.misc.sageinspect.sage_getsourcelines sagenb.inspect.getargspec = sage.misc.sageinspect.sage_getargspec ...
and if one wants to use the notebook in, say, mathematica, then one has to use other definitions (assigning sagenb.inspect.getsourcelines to a function that raises a NotImplementedError or so...),
The advantage for the topic of this ticket would be that we only needed to change one location, not two. The advantage for me would be: I am not a notebook user, and I don't really want to learn github for something that I don't use.
comment:7 Changed 4 years ago by SimonKing
Question: Should the encouraging message only be shown when a user interactively reads the documentation (by obj? in the notebook resp. in command line version), or should it also appear in the reference manual?
comment:8 Changed 3 years ago by knsam
- Status changed from new to needs_info
That I am changing the status to needs_info, let me just say that, we should be able to add this "Please contribute doctests" only in the interactive version. It would be very annoying to have this message in files where every function lacks doctests and the reference manual tells people "Please contribute doctests".
~KnS
comment:9 Changed 3 years ago by jdemeyer
- Milestone changed from sage-5.11 to sage-5.12
comment:10 Changed 2 years ago by vbraun_spam
- Milestone changed from sage-6.1 to sage-6.2
comment:11 Changed 2 years ago by vbraun_spam
- Milestone changed from sage-6.2 to sage-6.3
comment:12 Changed 22 months ago by vbraun_spam
- Milestone changed from sage-6.3 to sage-6.4
comment:13 Changed 9 months ago by chapoton
- Description modified (diff)
I'm guessing this will be a sort of meta-ticket, where you open another ticket for an undocumented function, and provide a link here. Hopefully then writing the doctest on the other ticket. Is that what you had in mind?
Dave