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

[georg.brandl]

Author: georg.brandl
Date: Sun Nov  2 21:04:24 2008
New Revision: 67074

Log:
Allow skipping members by event.


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

Modified: doctools/trunk/CHANGES
==============================================================================
--- doctools/trunk/CHANGES	(original)
+++ doctools/trunk/CHANGES	Sun Nov  2 21:04:24 2008
@@ -94,9 +94,12 @@
     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``,

Modified: doctools/trunk/doc/ext/autodoc.rst
==============================================================================
--- doctools/trunk/doc/ext/autodoc.rst	(original)
+++ doctools/trunk/doc/ext/autodoc.rst	Sun Nov  2 21:04:24 2008
@@ -240,3 +240,31 @@
 
 .. 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

Modified: doctools/trunk/sphinx/ext/autodoc.py
==============================================================================
--- doctools/trunk/sphinx/ext/autodoc.py	(original)
+++ doctools/trunk/sphinx/ext/autodoc.py	Sun Nov  2 21:04:24 2008
@@ -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 @@
             # 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 @@
     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')