Guido van Rossum added the comment: On Wed, Dec 4, 2013 at 10:25 PM, Terry J. Reedy <rep...@bugs.python.org> wrote: > I am familiar with running Sphinx on .rst files, but not on docstrings. > It looks like the docstrings use .rst markup. (Is this allowed in the > stdlib?)
I'm not sure if it is allowed, but it is certainly used plenty in some modules (perhaps those that started life as 3rd party packages). > (The output looks good enough for a first draft of a tkinter class/method > reference, which I would like to work on.) I won't stop you -- having *any* kind of docs for Tkinter sounds good to me! >> I understand that part of this [signature after class name] is due to the >> latter class having an __init__ with a reasonable docstring > > If dropbox.client is written in Python, as I presume, It is. > then I strongly suspect that the signature part of > class dropbox.client.DropboxClient( > oauth2_access_token, locale=None, rest_client=None) > comes from an inspect module method that examines the function attributes > other than .__doc__. Indeed. > If so, DropboxClient.__init__ docstring is irrelevant to the above. You could > test by commenting it out and rerunning the doc build. Yes. > The inspect methods do not work on C-coded functions (unless Argument Clinic > has fixed this for 3.4), which is why signatures are put in the docstrings > for C-coded objects. For C-coded classes, it is put in the class docstring > rather than the class.__init__ docstring. Perhaps it doesn't understand __new__? namedtuple actually generates Python code for a class definition using a template and then uses exec() on the filled-in template; the template defines only __new__ though. >> but the fact remains that namedtuple's default docstring produces >> poorly-looking documentation. > > 'x.__init__(...) initializes x; see help(type(x)) for signature' > > This is standard boilerplate for C-coded .__init__.__doc__. > Raymond just copied it. He didn't (it's not in the template). It is the dummy __init__ that tuple inherits from object (the docstring is in the __init__ wrapper in typeobject.c). >>>> int.__init__.__doc__ > 'x.__init__(...) initializes x; see help(type(x)) for signature' >>>> list.__init__.__doc__ > 'x.__init__(...) initializes x; see help(type(x)) for signature' ---------- _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue16669> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
