classification
Title: Autodoc's autoclass directive should include constructor docstring
Type: behavior Stage:
Components: Documentation tools (Sphinx) Versions: Python 2.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: georg.brandl Nosy List: abhik, georg.brandl
Priority: normal Keywords:

Created on 2008-04-30 14:04 by abhik, last changed 2008-05-07 20:21 by abhik. This issue is now closed.

Messages (3)
msg66002 - (view) Author: Abhik Shah (abhik) Date: 2008-04-30 14:03
The autoclass directive adds the class constructor's argspec to the header and shows the class docstring 
below it but doesn't add the constructor's docstring.  I usually use the class docstring to describe the 
class and the constructor's docstring to describe the constructor arguments so if the constructor argspec 
is being shown, I would expect the description of it to be included below.

Result of svn diff sphinx/ext/autodoc.py:

Index: sphinx/ext/autodoc.py
===================================================================
--- sphinx/ext/autodoc.py	(revision 62582)
+++ sphinx/ext/autodoc.py	(working copy)
@@ -154,6 +154,13 @@
     result.append(indent + '.. %s:: %s%s' % (what, qualname, args), '<autodoc>')
     result.append('', '<autodoc>')
 
+    # added by abhik (4/29/08)
+    if what == 'class':
+        initdoc = inspect.getdoc(getattr(todoc, '__init__'))
+        if initdoc:
+            docstring = docstring if docstring else ''
+            docstring += "\n" + indent + initdoc
+
     # the module directive doesn't like content
     if what != 'module':
         indent += '   '


I don't know how other people would expect autodoc to work so maybe this behavior could be controlled by 
a config param?
msg66200 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-05-04 09:38
Okay, I added a config value ("autoclass_content") in r62697. Let me
know what you think!
msg66372 - (view) Author: Abhik Shah (abhik) Date: 2008-05-07 20:21
Works great.. Thanks!

On Sun, May 4, 2008 at 5:38 AM, Georg Brandl <report@bugs.python.org> wrote:
>
>  Georg Brandl <georg@python.org> added the comment:
>
>  Okay, I added a config value ("autoclass_content") in r62697. Let me
>  know what you think!
>
>  ----------
>  resolution:  -> fixed
>  status: open -> closed
>
>
>
>  __________________________________
>  Tracker <report@bugs.python.org>
>  <http://bugs.python.org/issue2726>
>  __________________________________
>
History
Date User Action Args
2008-05-07 20:21:03abhiksetmessages: + msg66372
2008-05-04 09:38:02georg.brandlsetstatus: open -> closed
resolution: fixed
messages: + msg66200
2008-04-30 14:04:12abhikcreate