Allow skipping members by event.

3 files changed, 45 insertions, 3 deletions

diff --git a/CHANGES b/CHANGES
index e1d01e1b..cbdd18c3 100644
--- a/CHANGES
+++ b/CHANGES
@@ -94,9 +94,12 @@ New features added
     creates links to Sphinx documentation of Python objects in other
     projects.
 
-  - sphinx.doc.autodoc has a new event ``autodoc-process-signature``
+  - sphinx.ext.autodoc has a new event ``autodoc-process-signature``
     that allows tuning function signature introspection.
 
+  - sphinx.ext.autodoc has a new event ``autodoc-skip-member`` that allows
+    tuning which members are included in the generated content.
+
   - Respect __all__ when autodocumenting module members.
 
   - The `automodule` directive now supports the ``synopsis``,
diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst
index e1229521..993f971a 100644
--- a/doc/ext/autodoc.rst
+++ b/doc/ext/autodoc.rst
@@ -240,3 +240,31 @@ needed docstring processing in event :event:`autodoc-process-docstring`:
 
 .. autofunction:: cut_lines
 .. autofunction:: between
+
+
+Skipping members
+----------------
+
+autodoc allows the user to define a custom method for determining whether a
+member should be included in the documentation by using the following event:
+
+.. event:: autodoc-skip-member (app, what, name, obj, skip, options)
+
+   .. versionadded:: 0.5
+
+   Emitted when autodoc has to decide whether a member should be included in the
+   documentation.  The member is excluded if a handler returns ``True``.  It is
+   included if the handler returns ``False``.
+
+   :param app: the Sphinx application object
+   :param what: the type of the object which the docstring belongs to (one of
+      ``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``,
+      ``"attribute"``)
+   :param name: the fully qualified name of the object
+   :param obj: the object itself
+   :param skip: a boolean indicating if autodoc will skip this member if the user
+      handler does not override the decision
+   :param options: the options given to the directive: an object with attributes
+      ``inherited_members``, ``undoc_members``, ``show_inheritance`` and
+      ``noindex`` that are true if the flag option of same name was given to the
+      auto directive
diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py
index 21f80533..f77be89c 100644
--- a/sphinx/ext/autodoc.py
+++ b/sphinx/ext/autodoc.py
@@ -7,7 +7,7 @@
     the doctree, thus avoiding duplication between docstrings and documentation
     for those who like elaborate docstrings.
 
-    :copyright: 2008 by Georg Brandl, Pauli Virtanen.
+    :copyright: 2008 by Georg Brandl, Pauli Virtanen, Martin Hans.
     :license: BSD.
 """
 
@@ -526,10 +526,20 @@ class RstGenerator(object):
             # ignore members whose name starts with _ by default
             if _all and membername.startswith('_'):
                 continue
+
             # ignore undocumented members if :undoc-members: is not given
             doc = getattr(member, '__doc__', None)
-            if not self.options.undoc_members and not doc:
+            skip = not self.options.undoc_members and not doc
+            # give the user a chance to decide whether this member should be skipped
+            if self.env.app:
+                # let extensions preprocess docstrings
+                skip_user = self.env.app.emit_firstresult(
+                    'autodoc-skip-member', what, membername, member, skip, self.options)
+                if skip_user is not None:
+                    skip = skip_user
+            if skip:
                 continue
+
             if what == 'module':
                 if isinstance(member, types.FunctionType):
                     memberwhat = 'function'
@@ -645,3 +655,4 @@ def setup(app):
     app.add_config_value('autoclass_content', 'class', True)
     app.add_event('autodoc-process-docstring')
     app.add_event('autodoc-process-signature')
+    app.add_event('autodoc-skip-member')