Opened 4 years ago
Last modified 4 years ago
#22611 closed enhancement
Replace _sage_doc_ by a __doc__ descriptor — at Version 8
Reported by:  jdemeyer  Owned by:  

Priority:  major  Milestone:  sage7.6 
Component:  documentation  Keywords:  days85 
Cc:  hivert, nthiery  Merged in:  
Authors:  Jeroen Demeyer  Reviewers:  
Report Upstream:  N/A  Work issues:  
Branch:  u/jdemeyer/ticket/22611 (Commits, GitHub, GitLab)  Commit:  fa42d8eb1966a7e1ade67bb40b42a80bb04059b1 
Dependencies:  Stopgaps: 
Description (last modified by )
Currently, the method _sage_doc_
is used to implement custom documentation for instances of a class. Such a use case makes sense, but it should be implemented as the __doc__
attribute instead of the Sagespecific _sage_doc_
.
I tried various ways of implementing this and I found several Cython bugs along the way. The current solution is not the cleanest, but it works in all cases (Cython and Python, extension types and normal classes).
In the cases where _sage_doc_
was implemented for a base class, this patch requires adding @InstanceDoc
to every subclass. This is because Python never inherits the __doc__
attribute. There is a way around this using a metaclass, but I avoided that because metaclasses have their own problems (see #21681).
Change History (8)
comment:1 Changed 4 years ago by
 Description modified (diff)
 Keywords days85 added
comment:2 Changed 4 years ago by
 Branch set to u/jdemeyer/ticket/22611
comment:3 Changed 4 years ago by
 Cc hivert nthiery added
 Commit set to 326465738e5a563ebffc86196f400829650cee63
 Description modified (diff)
 Status changed from new to needs_review
comment:4 Changed 4 years ago by
 Commit changed from 326465738e5a563ebffc86196f400829650cee63 to fa42d8eb1966a7e1ade67bb40b42a80bb04059b1
Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:
fa42d8e  Replace _sage_doc_ by a __doc__ descriptor

comment:5 Changed 4 years ago by
There was an issue building the docs due to src/sage/parallel/decorate.py
. I did not understand the problem but I fixed it anyway with

src/sage/parallel/decorate.py
diff git a/src/sage/parallel/decorate.py b/src/sage/parallel/decorate.py index ebc06e2..3305724 100644
a b for a in args[0])) 284 287 sage: sage_getdoc(p(f)) 285 288 'Test docstring\n' 286 289 """ 287 from sage.misc.sageinspect import sage_getdoc 288 return sage_getdoc(self.func) 290 return self.func.__doc__ 289 291 290 292 291 293 def parallel(p_iter='fork', ncpus=None, **kwds):
comment:6 Changed 4 years ago by
In ticket description: and I was various Cython bugs along the way
!?
comment:7 Changed 4 years ago by
 Description modified (diff)
comment:8 Changed 4 years ago by
 Description modified (diff)
New commits:
Replace _sage_doc_ by a __doc__ descriptor