Implement prepare_docstring filter that wraps Sphinx's

This allows us to output docstrings in a reasonable fashion.

autoapi/mappers/base.py

@@ -7,6 +7,7 @@ import unidecode
 from jinja2 import Environment, FileSystemLoader, TemplateNotFound
 from sphinx.util.console import darkgreen, bold
 from sphinx.util.osutil import ensuredir
+from sphinx.util.docstrings import prepare_docstring
 
 from ..settings import API_ROOT
 
@@ -153,6 +154,10 @@ class PythonMapperBase(object):
             return '.'.join(pieces)
 
 
+def _wrapped_prepare(value):
+    return '\n'.join(prepare_docstring(value))
+
+
 class SphinxMapperBase(object):
 
     '''Base class for mapping `PythonMapperBase` objects to Sphinx.
@@ -177,6 +182,7 @@ class SphinxMapperBase(object):
             # trim_blocks=True,
             # lstrip_blocks=True,
         )
+        self.jinja_env.filters['prepare_docstring'] = _wrapped_prepare
 
         self.url_root = url_root
 

autoapi/templates/python/class.rst

@@ -2,8 +2,7 @@
 
    {%- if obj.docstring %}
 
-   .. autoapi-nested-parse::
+   {{ obj.docstring|prepare_docstring|indent(3) }}
-      {{ obj.docstring|indent(6) }}
 
    {% endif %}
 

autoapi/templates/python/function.rst

@@ -3,7 +3,7 @@
 .. function:: {{ obj.name }}({{ obj.args|join(',') }})
 
    {% if obj.docstring %}
-   {{ obj.docstring.strip()|indent(3) }}
+   {{ obj.docstring|prepare_docstring|indent(3) }}
    {% endif %}
 
 {% endif %}

autoapi/templates/python/member.rst

@@ -1,4 +1,4 @@
 .. {{ obj.type }}:: {{ obj.name }}
 
-   {{ obj.docstring|indent(3) }}
+   {{ obj.docstring|prepare_docstring|indent(3) }}
 

autoapi/templates/python/method.rst

@@ -3,7 +3,7 @@
 .. method:: {{ obj.name }}({{ obj.args[1:]|join(',') }})
 
    {% if obj.docstring %}
-   {{ obj.docstring|indent(3) }}
+   {{ obj.docstring|prepare_docstring|indent(3) }}
    {% endif %}
 
 {% endif %}

autoapi/templates/python/module.rst

@@ -6,7 +6,7 @@
 {%- if obj.docstring %}
 
 .. autoapi-nested-parse::
-   {{ obj.docstring|indent(3) }}
+   {{ obj.docstring|prepare_docstring|indent(3) }}
 
 {% endif %}