This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author gvanrossum
Recipients Ankur.Ankan, eric.snow, giampaolo.rodola, gvanrossum, rhettinger, serhiy.storchaka, terry.reedy
Date 2013-12-05.18:36:58
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <CAP7+vJ+UnT=6FUZc4usg-Sh1bYU=aWma=hkwa3dDUkofOoDN0w@mail.gmail.com>
In-reply-to <1386224710.39.0.826486583806.issue16669@psf.upfronthosting.co.za>
Content
On Wed, Dec 4, 2013 at 10:25 PM, Terry J. Reedy <report@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'
History
Date User Action Args
2013-12-05 18:36:59gvanrossumsetrecipients: + gvanrossum, rhettinger, terry.reedy, giampaolo.rodola, eric.snow, serhiy.storchaka, Ankur.Ankan
2013-12-05 18:36:59gvanrossumlinkissue16669 messages
2013-12-05 18:36:58gvanrossumcreate