[issue16669] Docstrings for namedtuple

[Guido van Rossum]

Guido van Rossum added the comment:

I don't know if it's worth reopening this, but I had a need for generating docs including attribute docstrings for a namedtuple class using Sphinx, and I noticed a few things...

(1) Regarding there not being demand: There's a StackOverflow question for this with 17 "ups" on the question and 22 on the best answer: http://stackoverflow.com/questions/1606436/adding-docstrings-to-namedtuples-in-python

(2) The default autodocs produced by sphinx look dreadful (e.g. https://www.dropbox.com/s/nakxsslhb588tu1/Screenshot%202013-12-04%2013.29.13.png) -- note the duplication of the class name, the line break before the signature, and the listing of attributes in alphabetical order with useless boilerplate.  Here's what I would *like* to produce: (though there's probably too much whitespace :-): https://www.dropbox.com/s/j11uismbeo6rrzx/Screenshot%202013-12-04%2013.31.44.png

(3) In Python 2.7 you can't assign to the __doc__ class attribute.

I would really appreciate some way to set the docstring for the class as a whole as well as for each property, so they come out correct in Sphinx (and help()), preferably without having to manually assign doc strings or write the class by hand without using namedtuple at all.  (The latter will become very verbose, each property has to look like this:

    @property
    def handle(self):
        """The datastore handle (a string)."""
        return self[1]
)

----------
nosy: +gvanrossum

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue16669>
_______________________________________