From 309377fbbf10ee7bea1eb7e944abfd7bd47b3aea Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 17 Jun 2008 09:24:11 +0000 Subject: [PATCH] Support inheritance display in autoclass, thanks to mdboom. --- CHANGES | 4 ++ doc/ext/autodoc.rst | 102 ++++++++++++++++++++++-------------------- sphinx/ext/autodoc.py | 39 +++++++++++----- 3 files changed, 85 insertions(+), 60 deletions(-) diff --git a/CHANGES b/CHANGES index 0825a89c8..db95e93af 100644 --- a/CHANGES +++ b/CHANGES @@ -60,6 +60,10 @@ New features added 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 ---------- diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index 48ca04c21..cf4dd5614 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -46,54 +46,6 @@ directive. Noodle's docstring. - If you want to automatically document members, there's a ``members`` - option:: - - .. 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: eat, slurp - - will document exactly the specified members. - - Members without docstrings will be left out, unless you give the - ``undoc-members`` flag option:: - - .. autoclass:: Noodle - :members: - :undoc-members: - - .. 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: - :inherited-members: - - This can be combined with ``undoc-members`` to document *all* available - members of the class or module. - - .. 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: - - :: - - .. autoclass:: Noodle(type) - - .. automethod:: eat(persona) - - This is useful if the signature from the method is hidden by a decorator. - 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). @@ -108,6 +60,60 @@ directive. Boil the noodle *time* minutes. + **Options and advanced usage** + + * If you want to automatically document members, there's a ``members`` + option:: + + .. 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: eat, slurp + + will document exactly the specified members. + + * Members without docstrings will be left out, unless you give the + ``undoc-members`` flag option:: + + .. autoclass:: Noodle + :members: + :undoc-members: + + * 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: + :inherited-members: + + This can be combined with ``undoc-members`` to document *all* available + members of the class or module. + + .. versionadded:: 0.3 + + * 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(type) + + .. automethod:: eat(persona) + + 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:: In an :dir:`automodule` directive with the ``members`` option set, only diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index 486591e1c..35eec9134 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -33,6 +33,10 @@ _charset_re = re.compile(r'coding[:=]\s*([-\w.]+)') _module_charsets = {} +class Options(object): + pass + + class AutodocReporter(object): """ A reporter replacement that assigns the correct source name @@ -185,8 +189,8 @@ def format_signature(what, obj): 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 @@ def generate_rst(what, name, members, inherited, undoc, add_content, document, result.append(indent + u' :module: %s' % mod, '') result.append(u'', '') + 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), '') + # the module directive doesn't have content if what != 'module': indent += u' ' @@ -348,7 +360,7 @@ def generate_rst(what, name, members, inherited, undoc, add_content, document, 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 @@ def generate_rst(what, name, members, inherited, undoc, add_content, document, 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 @@ def generate_rst(what, name, members, inherited, undoc, add_content, document, 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 @@ def _auto_directive(dirname, arguments, options, content, lineno, 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 members_directive(arg): 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,