Anonymous avatar Anonymous committed 57b6349

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

Comments (0)

Files changed (4)

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

doc/ext/autodoc.rst

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

sphinx/application.py

     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*

sphinx/ext/autodoc.py

         objpath = [cls, obj]
 
     result = ViewList()
+    docstrings = []
 
     if mod is None:
         warning = document.reporter.warning(
             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 '
         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))
+    if module is not None:
+        charset = get_module_charset(module)
+        docstrings = [docstring.decode(charset) for docstring in docstrings]
 
-    docstring = prepare_docstring(docstring)
-    for i, line in enumerate(docstring):
-        result.append(indent + line, '<docstring of %s>' % name, i)
+    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:
     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)
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.