Opened 2 years ago

Last modified 3 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.3
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 SimonKing)

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 (11)

comment:1 Changed 2 years ago by SimonKing

  • Description modified (diff)

comment:2 Changed 2 years ago by drkirkby

  • Cc drkirkby added

comment:3 follow-up: Changed 2 years ago by 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?

Dave

comment:4 in reply to: ↑ 3 Changed 2 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: Changed 2 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 2 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.

Last edited 2 years ago by SimonKing (previous) (diff)

comment:7 Changed 2 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 17 months 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 12 months ago by jdemeyer

  • Milestone changed from sage-5.11 to sage-5.12

comment:10 Changed 6 months ago by vbraun_spam

  • Milestone changed from sage-6.1 to sage-6.2

comment:11 Changed 3 months ago by vbraun_spam

  • Milestone changed from sage-6.2 to sage-6.3
Note: See TracTickets for help on using tickets.