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 terry.reedy
Recipients Ankur.Ankan, eric.snow, giampaolo.rodola, gvanrossum, rhettinger, serhiy.storchaka, terry.reedy
Date 2013-12-05.06:25:09
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1386224710.39.0.826486583806.issue16669@psf.upfronthosting.co.za>
In-reply-to
Content
> I find the help() output way too verbose with its endless listing of all the built-in behaviors.)

Then you might agree to a patch, on a separate issue. Let's set help aside for the moment.

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?)  (The output looks good enough for a first draft of a tkinter class/method reference, which I would like to work on.)

> 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, 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__. If so, DropboxClient.__init__ docstring is irrelevant to the above. You could test by commenting it out and rerunning the doc build.

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.

> 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.

>>> 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'

I will try to explain 'property transparency/equivalence' in another post, when I am fresher, and after reading the autodoc reference, so you can understand enough to agree or not. My reference to a possible alternate implementation of named tuple was part of the failed explanation of 'property transparency'. I am not proposing a change now.
History
Date User Action Args
2013-12-05 06:25:10terry.reedysetrecipients: + terry.reedy, gvanrossum, rhettinger, giampaolo.rodola, eric.snow, serhiy.storchaka, Ankur.Ankan
2013-12-05 06:25:10terry.reedysetmessageid: <1386224710.39.0.826486583806.issue16669@psf.upfronthosting.co.za>
2013-12-05 06:25:10terry.reedylinkissue16669 messages
2013-12-05 06:25:09terry.reedycreate