Opened 5 years ago

Last modified 5 years ago

#22611 closed enhancement

Replace _sage_doc_ by a __doc__ descriptor — at Version 8

Reported by: jdemeyer Owned by:
Priority: major Milestone: sage-7.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:

Status badges

Description (last modified by jdemeyer)

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 Sage-specific _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 5 years ago by jdemeyer

  • Description modified (diff)
  • Keywords days85 added

comment:2 Changed 5 years ago by jdemeyer

  • Branch set to u/jdemeyer/ticket/22611

comment:3 Changed 5 years ago by jdemeyer

  • Cc hivert nthiery added
  • Commit set to 326465738e5a563ebffc86196f400829650cee63
  • Description modified (diff)
  • Status changed from new to needs_review

New commits:

3264657Replace _sage_doc_ by a __doc__ descriptor

comment:4 Changed 5 years ago by git

  • Commit changed from 326465738e5a563ebffc86196f400829650cee63 to fa42d8eb1966a7e1ade67bb40b42a80bb04059b1

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

fa42d8eReplace _sage_doc_ by a __doc__ descriptor

comment:5 Changed 5 years ago by jdemeyer

There was an issue building the docs due to src/sage/parallel/ I did not understand the problem but I fixed it anyway with

  • src/sage/parallel/

    diff --git a/src/sage/parallel/ b/src/sage/parallel/
    index ebc06e2..3305724 100644
    a b for a in args[0])) 
    284287            sage: sage_getdoc(p(f))
    285288            'Test docstring\n'
    286289        """
    287         from sage.misc.sageinspect import sage_getdoc
    288         return sage_getdoc(self.func)
     290        return self.func.__doc__
    291293def parallel(p_iter='fork', ncpus=None, **kwds):

comment:6 Changed 5 years ago by vdelecroix

In ticket description: and I was various Cython bugs along the way!?

comment:7 Changed 5 years ago by jdemeyer

  • Description modified (diff)

comment:8 Changed 5 years ago by jdemeyer

  • Description modified (diff)
Note: See TracTickets for help on using tickets.