[Python-checkins] r64331 - in doctools/trunk: CHANGES doc/ext/autodoc.rst sphinx/ext/autodoc.py
georg.brandl
python-checkins at python.org
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,
More information about the Python-checkins
mailing list