Add general docstring processing support with a new event in autodoc.

3 files changed, 44 insertions, 7 deletions

diff --git a/doc/conf.py b/doc/conf.py
index bead46107..06dca15df 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -131,8 +131,6 @@ latex_logo = '_static/sphinx.png'
 # Documents to append as an appendix to all manuals.
 #latex_appendices = []
 
-automodule_skip_lines = 4
-
 
 # Extension interface
 # -------------------
@@ -180,6 +178,8 @@ def parse_event(env, sig, signode):
 
 
 def setup(app):
+    from sphinx.ext.autodoc import cut_lines
+    app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
     app.add_description_unit('directive', 'dir', 'pair: %s; directive', parse_directive)
     app.add_description_unit('role', 'role', 'pair: %s; role', parse_role)
     app.add_description_unit('confval', 'confval', 'pair: %s; configuration value')
diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst
index edd0537a6..deff82b4b 100644
--- a/doc/ext/appapi.rst
+++ b/doc/ext/appapi.rst
@@ -162,24 +162,24 @@ package.
 Sphinx core events
 ------------------
 
-These events are known to the core.  The arguments showed are given to the
+These events are known to the core.  The arguments shown are given to the
 registered event handlers.
 
-.. event:: builder-inited ()
+.. event:: builder-inited (app)
 
    Emitted the builder object has been created.
 
-.. event:: doctree-read (doctree)
+.. event:: doctree-read (app, doctree)
 
    Emitted when a doctree has been parsed and read by the environment, and is
    about to be pickled.
 
-.. event:: doctree-resolved (doctree, docname)
+.. event:: doctree-resolved (app, doctree, docname)
 
    Emitted when a doctree has been "resolved" by the environment, that is, all
    references and TOCs have been inserted.
 
-.. event:: page-context (pagename, templatename, context, doctree)
+.. event:: page-context (app, pagename, templatename, context, doctree)
 
    Emitted when the HTML builder has created a context dictionary to render a
    template with -- this can be used to add custom elements to the context.
diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst
index 50e9efc7f..2d329af3b 100644
--- a/doc/ext/autodoc.rst
+++ b/doc/ext/autodoc.rst
@@ -148,6 +148,10 @@ There are also new config values that you can set:
    fields with version control tags, that you don't want to put in the generated
    documentation.
 
+   .. deprecated:: 0.4
+      Use the more versatile docstring processing provided by
+      :event:`autodoc-process-docstring`.
+
 .. confval:: autoclass_content
 
    This value selects what content will be inserted into the main body of an
@@ -164,3 +168,36 @@ There are also new config values that you can set:
       Only the ``__init__`` method's docstring is inserted.
 
    .. versionadded:: 0.3
+
+
+Docstring preprocessing
+-----------------------
+
+.. versionadded:: 0.4
+
+autodoc provides the following additional event:
+
+.. event:: autodoc-process-docstring (app, what, name, obj, options, lines)
+
+   Emitted when autodoc has read and processed a docstring.  *lines* is a list
+   of strings -- the lines of the processed docstring -- that the event handler
+   can modify **in place** to change what Sphinx puts into the output.
+
+   :param app: the Sphinx application object
+   :param what: the type of the object which the docstring belongs to (one of
+      ``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``,
+      ``"attribute"``)
+   :param name: the fully qualified name of the object
+   :param obj: the object itself
+   :param options: the options given to the directive: an object with attributes
+      ``inherited_members``, ``undoc_members``, ``show_inheritance`` and
+      ``noindex`` that are true if the flag option of same name was given to the
+      auto directive
+   :param lines: the lines of the docstring, see above
+
+
+The :mod:`sphinx.ext.autodoc` module provides factory functions for commonly
+needed docstring processing:
+
+.. autofunction:: cut_lines
+.. autofunction:: between