Terry J. Reedy added the comment:
> 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.
----------
_______________________________________
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
