#520: Provide ``special-members`` option for autodoc directives.

4 files changed, 29 insertions, 9 deletions

diff --git a/CHANGES b/CHANGES
index 544db77e..297c8c94 100644
--- a/CHANGES
+++ b/CHANGES
@@ -14,6 +14,8 @@ Release 1.1 (in development)
 
 * #176: Provide ``private-members`` option for autodoc directives.
 
+* #520: Provide ``special-members`` option for autodoc directives.
+
 * #138: Add an ``index`` role, to make inline index entries.
 
 * #443: Allow referencing external graphviz files.
diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst
index ee58c060..8026972c 100644
--- a/doc/ext/autodoc.rst
+++ b/doc/ext/autodoc.rst
@@ -103,12 +103,20 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
            :members:
            :undoc-members:
 
-   * Private members will be included if the ``private-members`` flag option is
-     given::
+   * "Private" members (that is, those named like ``_private`` or ``__private``)
+     will be included if the ``private-members`` flag option is given.
+
+     .. versionadded:: 1.1
+
+   * Python "special" members (that is, those named like ``__special__``) will
+     be included if the ``special-members`` flag option is given::
 
         .. autoclass:: my.Class
            :members:
            :private-members:
+           :special-members:
+
+     would document both "private" and "special" members of the class.
 
      .. versionadded:: 1.1
 
@@ -262,8 +270,8 @@ There are also new config values that you can set:
 
    This value is a list of autodoc directive flags that should be automatically
    applied to all autodoc directives.  The supported flags are ``'members'``,
-   ``'undoc-members'``, ``'private-members'``, ``'inherited-members'`` and
-   ``'show-inheritance'``.
+   ``'undoc-members'``, ``'private-members'``, ``'special-members'``,
+   ``'inherited-members'`` and ``'show-inheritance'``.
 
    If you set one of these flags in this config value, you can use a negated
    form, :samp:`'no-{flag}'`, in an autodoc directive, to disable it once.
diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py
index 64b3d2d4..993f690a 100644
--- a/sphinx/ext/autodoc.py
+++ b/sphinx/ext/autodoc.py
@@ -520,6 +520,8 @@ class Documenter(object):
 
         - they are private (except if given explicitly or the private-members
           option is set)
+        - they are special methods (except if given explicitly or the
+          special-members option is set)
         - they are undocumented (except if the undoc-members option is set)
 
         The user can override the skipping decision by connecting to the
@@ -540,7 +542,11 @@ class Documenter(object):
             # if isattr is True, the member is documented as an attribute
             isattr = False
 
-            if want_all and membername.startswith('_'):
+            if want_all and membername.startswith('__') and \
+                   membername.endswith('__') and len(membername) > 4:
+                # special __methods__
+                skip = not self.options.special_members
+            elif want_all and membername.startswith('_'):
                 # ignore members whose name starts with _ by default
                 skip = not self.options.private_members
             elif (namespace, membername) in attr_docs:
@@ -714,7 +720,7 @@ class ModuleDocumenter(Documenter):
         'show-inheritance': bool_option, 'synopsis': identity,
         'platform': identity, 'deprecated': bool_option,
         'member-order': identity, 'exclude-members': members_set_option,
-        'private-members': bool_option,
+        'private-members': bool_option, 'special-members': bool_option,
     }
 
     @classmethod
@@ -868,7 +874,8 @@ class ClassDocumenter(ModuleLevelDocumenter):
         'members': members_option, 'undoc-members': bool_option,
         'noindex': bool_option, 'inherited-members': bool_option,
         'show-inheritance': bool_option, 'member-order': identity,
-        'exclude-members': members_set_option, 'private-members': bool_option,
+        'exclude-members': members_set_option,
+        'private-members': bool_option, 'special-members': bool_option,
     }
 
     @classmethod
@@ -1135,8 +1142,10 @@ class AutoDirective(Directive):
     _special_attrgetters = {}
 
     # flags that can be given in autodoc_default_flags
-    _default_flags = set(['members', 'undoc-members', 'inherited-members',
-                          'show-inheritance', 'private-members'])
+    _default_flags = set([
+        'members', 'undoc-members', 'inherited-members', 'show-inheritance',
+        'private-members', 'special-members',
+    ])
 
     # standard docutils directive settings
     has_content = True
diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py
index 7ab9f055..d70fa260 100644
--- a/tests/test_autodoc.py
+++ b/tests/test_autodoc.py
@@ -31,6 +31,7 @@ def setup_module():
         inherited_members = False,
         undoc_members = False,
         private_members = False,
+        special_members = False,
         show_inheritance = False,
         noindex = False,
         synopsis = '',