#176: Provide `private-members` option for autodoc directives.

CHANGES

@@ -12,6 +12,8 @@ Release 1.1 (in development)
 
 * #460: Allow limiting the depth of section numbers for HTML.
 
+* #176: Provide ``private-members`` option for autodoc directives.
+
 * #138: Add an ``index`` role, to make inline index entries.
 
 * #443: Allow referencing external graphviz files.

doc/ext/autodoc.rst

@@ -93,8 +93,8 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
         .. autoclass:: Noodle
            :members: eat, slurp
 
-   * If you want to make the ``members`` option the default, see
-     :confval:`autodoc_default_flags`.
+   * If you want to make the ``members`` option (or other flag options described
+     below) the default, see :confval:`autodoc_default_flags`.
 
    * Members without docstrings will be left out, unless you give the
      ``undoc-members`` flag option::
@@ -103,6 +103,15 @@ 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::
+
+        .. autoclass:: my.Class
+           :members:
+           :private-members:
+
+     .. versionadded:: 1.1
+
    * For classes and exceptions, members inherited from base classes will be
      left out, unless you give the ``inherited-members`` flag option, in
      addition to ``members``::
@@ -152,8 +161,8 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
 
      .. versionadded:: 0.5
 
-   * :rst:dir:`automodule` and :rst:dir:`autoclass` also has an ``member-order`` option
-     that can be used to override the global value of
+   * :rst:dir:`automodule` and :rst:dir:`autoclass` also has an ``member-order``
+     option that can be used to override the global value of
      :confval:`autodoc_member_order` for one directive.
 
      .. versionadded:: 0.6
@@ -173,9 +182,9 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
 
 
 .. rst:directive:: autofunction
-               autodata
-               automethod
-               autoattribute
+                   autodata
+                   automethod
+                   autoattribute
 
    These work exactly like :rst:dir:`autoclass` etc., but do not offer the options
    used for automatic member documentation.
@@ -193,11 +202,11 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
 
           baz = 2
           """Docstring for class attribute Foo.baz."""
-          
+
           def __init__(self):
               #: Doc comment for instance attribute qux.
               self.qux = 3
-              
+
               self.spam = 4
               """Docstring for instance attribute spam."""
 
@@ -253,7 +262,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'``, ``'inherited-members'`` and ``'show-inheritance'``.
+   ``'undoc-members'``, ``'private-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.

sphinx/ext/autodoc.py

@@ -518,8 +518,9 @@ class Documenter(object):
 
         Members are skipped if
 
-        - they are private (except if given explicitly)
-        - they are undocumented (except if undoc-members is given)
+        - they are private (except if given explicitly or the private-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
         ``autodoc-skip-member`` event.
@@ -541,7 +542,7 @@ class Documenter(object):
 
             if want_all and membername.startswith('_'):
                 # ignore members whose name starts with _ by default
-                skip = True
+                skip = not self.options.private_members
             elif (namespace, membername) in attr_docs:
                 # keep documented attributes
                 skip = False
@@ -713,6 +714,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,
     }
 
     @classmethod
@@ -866,7 +868,7 @@ 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,
+        'exclude-members': members_set_option, 'private-members': bool_option,
     }
 
     @classmethod
@@ -1134,7 +1136,7 @@ class AutoDirective(Directive):
 
     # flags that can be given in autodoc_default_flags
     _default_flags = set(['members', 'undoc-members', 'inherited-members',
-                          'show-inheritance'])
+                          'show-inheritance', 'private-members'])
 
     # standard docutils directive settings
     has_content = True

tests/test_autodoc.py

@@ -30,6 +30,7 @@ def setup_module():
     options = Struct(
         inherited_members = False,
         undoc_members = False,
+        private_members = False,
         show_inheritance = False,
         noindex = False,
         synopsis = '',