From ffb2130b55d63b0db40144dd8eee6bd4bfa7181d Mon Sep 17 00:00:00 2001
From: Eric Holscher <eric@ericholscher.com>
Date: Fri, 4 Nov 2016 15:17:50 -0700
Subject: [PATCH] Implement prepare_docstring filter that wraps Sphinx's

This allows us to output docstrings in a reasonable fashion.
---
 autoapi/mappers/base.py               | 6 ++++++
 autoapi/templates/python/class.rst    | 3 +--
 autoapi/templates/python/function.rst | 2 +-
 autoapi/templates/python/member.rst   | 2 +-
 autoapi/templates/python/method.rst   | 2 +-
 autoapi/templates/python/module.rst   | 2 +-
 6 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/autoapi/mappers/base.py b/autoapi/mappers/base.py
index db439bb..3a86fa5 100644
--- a/autoapi/mappers/base.py
+++ b/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
 
diff --git a/autoapi/templates/python/class.rst b/autoapi/templates/python/class.rst
index 1f4fe4f..4e2e95d 100644
--- a/autoapi/templates/python/class.rst
+++ b/autoapi/templates/python/class.rst
@@ -2,8 +2,7 @@
 
    {%- if obj.docstring %}
 
-   .. autoapi-nested-parse::
-      {{ obj.docstring|indent(6) }}
+   {{ obj.docstring|prepare_docstring|indent(3) }}
 
    {% endif %}
 
diff --git a/autoapi/templates/python/function.rst b/autoapi/templates/python/function.rst
index e853603..8412892 100644
--- a/autoapi/templates/python/function.rst
+++ b/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 %}
\ No newline at end of file
diff --git a/autoapi/templates/python/member.rst b/autoapi/templates/python/member.rst
index 1f87d1f..2526660 100644
--- a/autoapi/templates/python/member.rst
+++ b/autoapi/templates/python/member.rst
@@ -1,4 +1,4 @@
 .. {{ obj.type }}:: {{ obj.name }}
 
-   {{ obj.docstring|indent(3) }}
+   {{ obj.docstring|prepare_docstring|indent(3) }}
 
diff --git a/autoapi/templates/python/method.rst b/autoapi/templates/python/method.rst
index 93957e7..51e7535 100644
--- a/autoapi/templates/python/method.rst
+++ b/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 %}
diff --git a/autoapi/templates/python/module.rst b/autoapi/templates/python/module.rst
index 1e3f1df..40778a8 100644
--- a/autoapi/templates/python/module.rst
+++ b/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 %}