[Python-checkins] r62697 - in doctools/trunk: CHANGES doc/ext/autodoc.rst sphinx/application.py sphinx/ext/autodoc.py

[georg.brandl]

Author: georg.brandl
Date: Sun May  4 11:37:37 2008
New Revision: 62697

Log:
#2726: allow selecting what gets inserted into an autoclass directive.


Modified:
   doctools/trunk/CHANGES
   doctools/trunk/doc/ext/autodoc.rst
   doctools/trunk/sphinx/application.py
   doctools/trunk/sphinx/ext/autodoc.py

Modified: doctools/trunk/CHANGES
==============================================================================
--- doctools/trunk/CHANGES	(original)
+++ doctools/trunk/CHANGES	Sun May  4 11:37:37 2008
@@ -22,6 +22,12 @@
 * A new config value, `latex_use_parts`, can be used to enable parts in LaTeX
   documents.
 
+* Autodoc now skips inherited members for classes, unless you give the
+  new ``inherited-members`` option.
+
+* A new config value, `autoclass_content`, selects if the docstring of the
+  class' ``__init__`` method is added to the directive's body.
+
 Bugs fixed
 ----------
 

Modified: doctools/trunk/doc/ext/autodoc.rst
==============================================================================
--- doctools/trunk/doc/ext/autodoc.rst	(original)
+++ doctools/trunk/doc/ext/autodoc.rst	Sun May  4 11:37:37 2008
@@ -97,7 +97,7 @@
    used for automatic member documentation.
 
 
-There's also one new config value that you can set:
+There are also new config values that you can set:
 
 .. confval:: automodule_skip_lines
 
@@ -107,3 +107,20 @@
    docstring, which would then interfere with your sectioning, or automatic
    fields with version control tags, that you don't want to put in the generated
    documentation.
+
+.. confval:: autoclass_content
+
+   This value selects what content will be inserted into the main body of an
+   :dir:`autoclass` directive.  The possible values are:
+
+   ``"class"``
+      Only the class' docstring is inserted.  This is the default.  You can
+      still document ``__init__`` as a separate method using :dir:`automethod`
+      or the ``members`` option to :dir:`autoclass`.
+   ``"both"``
+      Both the class' and the ``__init__`` method's docstring are concatenated
+      and inserted.
+   ``"init"``
+      Only the ``__init__`` method's docstring is inserted.
+
+   .. versionadded:: 0.2.1

Modified: doctools/trunk/sphinx/application.py
==============================================================================
--- doctools/trunk/sphinx/application.py	(original)
+++ doctools/trunk/sphinx/application.py	Sun May  4 11:37:37 2008
@@ -226,6 +226,11 @@
     that renders templates given a template name and a context.
     """
 
+    def __init__(self):
+        """
+        Initialize the class.
+        """
+
     def init(self, builder):
         """
         Called by the builder to initialize the template system.  *builder*

Modified: doctools/trunk/sphinx/ext/autodoc.py
==============================================================================
--- doctools/trunk/sphinx/ext/autodoc.py	(original)
+++ doctools/trunk/sphinx/ext/autodoc.py	Sun May  4 11:37:37 2008
@@ -107,6 +107,7 @@
         objpath = [cls, obj]
 
     result = ViewList()
+    docstrings = []
 
     if mod is None:
         warning = document.reporter.warning(
@@ -129,7 +130,8 @@
             if hasattr(todoc, '__module__'):
                 if todoc.__module__ != mod:
                     return [], result
-        docstring = todoc.__doc__
+        if getattr(todoc, '__doc__', None):
+            docstrings.append(todoc.__doc__)
     except (ImportError, AttributeError):
         warning = document.reporter.warning(
             'autodoc can\'t import/find %s %r, check your spelling '
@@ -167,18 +169,35 @@
         indent += '   '
 
     # add docstring content
-    if what == 'module' and env.config.automodule_skip_lines and docstring:
-        docstring = '\n'.join(docstring.splitlines()
-                              [env.config.automodule_skip_lines:])
+    if what == 'module' and env.config.automodule_skip_lines and docstrings[0]:
+        docstrings[0] = '\n'.join(docstring.splitlines()
+                                  [env.config.automodule_skip_lines:])
+
+    # for classes, what the "docstring" is can be controlled via an option
+    if what in ('class', 'exception'):
+        content = env.config.autoclass_content
+        if content in ('both', 'init'):
+            initdocstring = getattr(todoc, '__init__', None).__doc__
+            # for new-style classes, no __init__ means default __init__
+            if initdocstring == object.__init__.__doc__:
+                initdocstring = None
+            if initdocstring:
+                if content == 'init':
+                    docstrings = [initdocstring]
+                else:
+                    docstrings.append('\n\n' + initdocstring)
+        # the default is only the class docstring
 
     # get the encoding of the docstring
     module = getattr(todoc, '__module__', None)
-    if module is not None and docstring is not None:
-        docstring = docstring.decode(get_module_charset(module))
-
-    docstring = prepare_docstring(docstring)
-    for i, line in enumerate(docstring):
-        result.append(indent + line, '<docstring of %s>' % name, i)
+    if module is not None:
+        charset = get_module_charset(module)
+        docstrings = [docstring.decode(charset) for docstring in docstrings]
+
+    for docstring in docstrings:
+        docstring = prepare_docstring(docstring)
+        for i, line in enumerate(docstring):
+            result.append(indent + line, '<docstring of %s>' % name, i)
 
     # add source content, if present
     if add_content:
@@ -313,3 +332,4 @@
     app.add_directive('automethod', auto_directive, 1, (1, 0, 1))
     app.add_directive('autoattribute', auto_directive, 1, (1, 0, 1))
     app.add_config_value('automodule_skip_lines', 0, True)
+    app.add_config_value('autoclass_content', 'class', True)