From d93b236545356f6ca4ba8dc16467bc49242b028c Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 4 May 2008 09:37:37 +0000 Subject: [PATCH] #2726: allow selecting what gets inserted into an autoclass directive. --- CHANGES | 6 ++++++ doc/ext/autodoc.rst | 19 ++++++++++++++++++- sphinx/application.py | 5 +++++ sphinx/ext/autodoc.py | 38 +++++++++++++++++++++++++++++--------- 4 files changed, 58 insertions(+), 10 deletions(-) diff --git a/CHANGES b/CHANGES index 63ed210d3..96289e966 100644 --- a/CHANGES +++ b/CHANGES @@ -22,6 +22,12 @@ New features added * A new config value, `latex_use_parts`, can be used to enable parts in LaTeX documents. +* Autodoc now skips inherited members for classes, unless you give the + new ``inherited-members`` option. + +* A new config value, `autoclass_content`, selects if the docstring of the + class' ``__init__`` method is added to the directive's body. + Bugs fixed ---------- diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index 5160cd8ba..80c6942cd 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -97,7 +97,7 @@ directive. used for automatic member documentation. -There's also one new config value that you can set: +There are also new config values that you can set: .. confval:: automodule_skip_lines @@ -107,3 +107,20 @@ There's also one new config value that you can set: docstring, which would then interfere with your sectioning, or automatic fields with version control tags, that you don't want to put in the generated documentation. + +.. confval:: autoclass_content + + This value selects what content will be inserted into the main body of an + :dir:`autoclass` directive. The possible values are: + + ``"class"`` + Only the class' docstring is inserted. This is the default. You can + still document ``__init__`` as a separate method using :dir:`automethod` + or the ``members`` option to :dir:`autoclass`. + ``"both"`` + Both the class' and the ``__init__`` method's docstring are concatenated + and inserted. + ``"init"`` + Only the ``__init__`` method's docstring is inserted. + + .. versionadded:: 0.2.1 diff --git a/sphinx/application.py b/sphinx/application.py index cfb9677d3..1982aa028 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -226,6 +226,11 @@ class TemplateBridge(object): that renders templates given a template name and a context. """ + def __init__(self): + """ + Initialize the class. + """ + def init(self, builder): """ Called by the builder to initialize the template system. *builder* diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index a17ebb3e0..89362e71f 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -107,6 +107,7 @@ def generate_rst(what, name, members, inherited, undoc, add_content, document, objpath = [cls, obj] result = ViewList() + docstrings = [] if mod is None: warning = document.reporter.warning( @@ -129,7 +130,8 @@ def generate_rst(what, name, members, inherited, undoc, add_content, document, if hasattr(todoc, '__module__'): if todoc.__module__ != mod: return [], result - docstring = todoc.__doc__ + if getattr(todoc, '__doc__', None): + docstrings.append(todoc.__doc__) except (ImportError, AttributeError): warning = document.reporter.warning( 'autodoc can\'t import/find %s %r, check your spelling ' @@ -167,18 +169,35 @@ def generate_rst(what, name, members, inherited, undoc, add_content, document, indent += ' ' # add docstring content - if what == 'module' and env.config.automodule_skip_lines and docstring: - docstring = '\n'.join(docstring.splitlines() - [env.config.automodule_skip_lines:]) + if what == 'module' and env.config.automodule_skip_lines and docstrings[0]: + docstrings[0] = '\n'.join(docstring.splitlines() + [env.config.automodule_skip_lines:]) + + # for classes, what the "docstring" is can be controlled via an option + if what in ('class', 'exception'): + content = env.config.autoclass_content + if content in ('both', 'init'): + initdocstring = getattr(todoc, '__init__', None).__doc__ + # for new-style classes, no __init__ means default __init__ + if initdocstring == object.__init__.__doc__: + initdocstring = None + if initdocstring: + if content == 'init': + docstrings = [initdocstring] + else: + docstrings.append('\n\n' + initdocstring) + # the default is only the class docstring # get the encoding of the docstring module = getattr(todoc, '__module__', None) - if module is not None and docstring is not None: - docstring = docstring.decode(get_module_charset(module)) + if module is not None: + charset = get_module_charset(module) + docstrings = [docstring.decode(charset) for docstring in docstrings] - docstring = prepare_docstring(docstring) - for i, line in enumerate(docstring): - result.append(indent + line, '' % name, i) + for docstring in docstrings: + docstring = prepare_docstring(docstring) + for i, line in enumerate(docstring): + result.append(indent + line, '' % name, i) # add source content, if present if add_content: @@ -313,3 +332,4 @@ def setup(app): app.add_directive('automethod', auto_directive, 1, (1, 0, 1)) app.add_directive('autoattribute', auto_directive, 1, (1, 0, 1)) app.add_config_value('automodule_skip_lines', 0, True) + app.add_config_value('autoclass_content', 'class', True)