From 92cb77a1315065dc206c880c65c83b87c8576070 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 3 Jan 2011 21:48:37 +0100 Subject: [PATCH] #176: Provide ``private-members`` option for autodoc directives. --- CHANGES | 2 ++ doc/ext/autodoc.rst | 30 ++++++++++++++++++++---------- sphinx/ext/autodoc.py | 12 +++++++----- tests/test_autodoc.py | 1 + 4 files changed, 30 insertions(+), 15 deletions(-) diff --git a/CHANGES b/CHANGES index ea7489af6..544db77ea 100644 --- a/CHANGES +++ b/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. diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index 68837a9a9..ee58c0602 100644 --- a/doc/ext/autodoc.rst +++ b/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. diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index 3b378001f..64b3d2d49 100644 --- a/sphinx/ext/autodoc.py +++ b/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 diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index 8f983471c..7ab9f0559 100644 --- a/tests/test_autodoc.py +++ b/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 = '',