Invite for contributing a doctest, if a user reads an untested function or method
|Reported by:||SimonKing||Owned by:||was|
|Component:||user interface||Keywords:||documentation untested|
|Report Upstream:||N/A||Work issues:|
Description (last modified by )
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!).