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

Tue Jun 17 11:24:11 CEST 2008

Author: georg.brandl
Date: Tue Jun 17 11:24:11 2008
New Revision: 64331
Log:
Support inheritance display in autoclass, thanks to mdboom.
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	Tue Jun 17 11:24:11 2008
@@ -60,6 +60,10 @@
 and classes now that override the signature got via introspection
 from Python code.
 
+ - The `autodoc` extension now offers a ``show-inheritance`` option
+ for autoclass that inserts a list of bases after the signature.
+
+
 Bugs fixed
 ----------
 
Modified: doctools/trunk/doc/ext/autodoc.rst
==============================================================================
--- doctools/trunk/doc/ext/autodoc.rst	(original)
+++ doctools/trunk/doc/ext/autodoc.rst	Tue Jun 17 11:24:11 2008
@@ -46,67 +46,73 @@
 
 Noodle's docstring.
 
- If you want to automatically document members, there's a ``members``
- option::
-
- .. autoclass:: Noodle
- :members:
+ The "auto" directives can also contain content of their own, it will be
+ inserted into the resulting non-auto directive source after the docstring
+ (but before any automatic member documentation).
 
- will document all non-private member functions and properties (that is, those
- whose name doesn't start with ``_``), while ::
+ Therefore, you can also mix automatic and non-automatic member documentation,
+ like so::
 
 .. autoclass:: Noodle
 :members: eat, slurp
 
- will document exactly the specified members.
+ .. method:: boil(time=10)
 
- Members without docstrings will be left out, unless you give the
- ``undoc-members`` flag option::
+ Boil the noodle *time* minutes.
 
- .. autoclass:: Noodle
- :members:
- :undoc-members:
+ **Options and advanced usage**
+ 
+ * If you want to automatically document members, there's a ``members``
+ option::
 
- .. versionadded:: 0.3
- 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``:
+ .. autoclass:: Noodle
+ :members:
 
- ::
+ will document all non-private member functions and properties (that is,
+ those whose name doesn't start with ``_``), while ::
 
- .. autoclass:: Noodle
- :members:
- :inherited-members:
+ .. autoclass:: Noodle
+ :members: eat, slurp
 
- This can be combined with ``undoc-members`` to document *all* available
- members of the class or module.
+ will document exactly the specified members.
 
- .. versionadded:: 0.4
- It's possible to override the signature for callable members (functions,
- methods, classes) with the regular syntax that will override the signature
- gained from instropection:
+ * Members without docstrings will be left out, unless you give the
+ ``undoc-members`` flag option::
 
- ::
+ .. autoclass:: Noodle
+ :members:
+ :undoc-members:
 
- .. autoclass:: Noodle(type)
+ * 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``::
 
- .. automethod:: eat(persona)
+ .. autoclass:: Noodle
+ :members:
+ :inherited-members:
 
- This is useful if the signature from the method is hidden by a decorator.
+ This can be combined with ``undoc-members`` to document *all* available
+ members of the class or module.
 
- The "auto" directives can also contain content of their own, it will be
- inserted into the resulting non-auto directive source after the docstring
- (but before any automatic member documentation).
+ .. versionadded:: 0.3
 
- Therefore, you can also mix automatic and non-automatic member documentation,
- like so::
+ * It's possible to override the signature for callable members (functions,
+ methods, classes) with the regular syntax that will override the signature
+ gained from instropection::
 
- .. autoclass:: Noodle
- :members: eat, slurp
+ .. autoclass:: Noodle(type)
 
- .. method:: boil(time=10)
+ .. automethod:: eat(persona)
 
- Boil the noodle *time* minutes.
+ This is useful if the signature from the method is hidden by a decorator.
+
+ .. versionadded:: 0.4
+
+ * The :dir:`autoclass` and :dir:`autoexception` directives also support a
+ flag option called ``show-inheritance``. When given, a list of base
+ classes will be inserted just below the class signature.
+
+ .. versionadded:: 0.4
 
 .. note::
 
Modified: doctools/trunk/sphinx/ext/autodoc.py
==============================================================================
--- doctools/trunk/sphinx/ext/autodoc.py	(original)
+++ doctools/trunk/sphinx/ext/autodoc.py	Tue Jun 17 11:24:11 2008
@@ -33,6 +33,10 @@
 _module_charsets = {}
 
 
+class Options(object):
+ pass
+
+
 class AutodocReporter(object):
 """
 A reporter replacement that assigns the correct source name
@@ -185,8 +189,8 @@
 return inspect.formatargspec(*argspec)
 
 
-def generate_rst(what, name, members, inherited, undoc, add_content, document,
- lineno, indent=u'', filename_set=None, check_module=False):
+def generate_rst(what, name, members, options, add_content, document, lineno,
+ indent=u'', filename_set=None, check_module=False):
 env = document.settings.env
 
 result = None
@@ -310,6 +314,14 @@
 result.append(indent + u' :module: %s' % mod, '<autodoc>')
 result.append(u'', '<autodoc>')
 
+ if options.show_inheritance and what in ('class', 'exception'):
+ if len(todoc.__bases__):
+ bases = [b.__module__ == '__builtin__' and
+ u':class:`%s`' % b.__name__ or
+ u':class:`%s.%s`' % (b.__module__, b.__name__)
+ for b in todoc.__bases__]
+ result.append(indent + u' Bases: %s' % ', '.join(bases), '<autodoc>')
+
 # the module directive doesn't have content
 if what != 'module':
 indent += u' '
@@ -348,7 +360,7 @@
 members_check_module = True
 all_members = inspect.getmembers(todoc)
 else:
- if inherited:
+ if options.inherited:
 # getmembers() uses dir() which pulls in members from all base classes
 all_members = inspect.getmembers(todoc)
 else:
@@ -362,7 +374,7 @@
 continue
 # ignore undocumented members if :undoc-members: is not given
 doc = getattr(member, '__doc__', None)
- if not undoc and not doc:
+ if not options.undoc and not doc:
 continue
 if what == 'module':
 if isinstance(member, types.FunctionType):
@@ -386,8 +398,8 @@
 continue
 full_membername = fullname + '.' + membername
 subwarn, subres = generate_rst(memberwhat, full_membername, ['__all__'],
- inherited, undoc, None, document, lineno,
- indent, check_module=members_check_module)
+ options, None, document, lineno, indent,
+ check_module=members_check_module)
 warnings.extend(subwarn)
 if subres is not None:
 result.extend(subres)
@@ -402,16 +414,18 @@
 content_offset, block_text, state, state_machine):
 what = dirname[4:] # strip "auto"
 name = arguments[0]
+ genopt = Options()
 members = options.get('members', [])
- inherited = 'inherited-members' in options
- if inherited and not members:
+ genopt.inherited = 'inherited-members' in options
+ if genopt.inherited and not members:
 # :inherited-members: implies :members:
 members = ['__all__']
- undoc = 'undoc-members' in options
+ genopt.undoc = 'undoc-members' in options
+ genopt.show_inheritance = 'show-inheritance' in options
 
 filename_set = set()
- warnings, result = generate_rst(what, name, members, inherited, undoc, content,
- state.document, lineno, filename_set=filename_set)
+ warnings, result = generate_rst(what, name, members, genopt, content, state.document,
+ lineno, filename_set=filename_set)
 if result is None:
 return warnings
 
@@ -455,7 +469,8 @@
 def setup(app):
 mod_options = {'members': members_directive, 'undoc-members': directives.flag}
 cls_options = {'members': members_directive, 'undoc-members': directives.flag,
- 'inherited-members': directives.flag}
+ 'inherited-members': directives.flag,
+ 'show-inheritance': directives.flag}
 app.add_directive('automodule', auto_directive_withmembers,
 1, (1, 0, 1), **mod_options)
 app.add_directive('autoclass', auto_directive_withmembers,
