Closes #1384: Parse and interpret See Also section the way NumpyDoc does

The NumpyDoc extension that is developed by the Numpy folks does a lot
of extra work interpreting See Also sections. It assumes that the contents
of the See Also will always be references to other functions/classes and
it tries to deduce what is being referenced.

I've ported their implementation for See Also sections written in the
Numpy style. There is NO extra interpretation done for See Also sections
that are written using the Google style.

3 files changed, 210 insertions, 0 deletions

diff --git a/LICENSE b/LICENSE
index 7aa7620b..85ce4a1d 100644
--- a/LICENSE
+++ b/LICENSE
@@ -244,3 +244,37 @@ HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 OTHER DEALINGS IN THE SOFTWARE.
+
+-------------------------------------------------------------------------------
+
+The included implementation of NumpyDocstring._parse_see_also_section was
+derived from code under the following license:
+
+-------------------------------------------------------------------------------
+
+Copyright (C) 2008 Stefan van der Walt <stefan@mentat.za.net>, Pauli Virtanen <pav@iki.fi>
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+ 1. Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+ 2. Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in
+    the documentation and/or other materials provided with the
+    distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+
+-------------------------------------------------------------------------------
diff --git a/sphinx/ext/napoleon/docstring.py b/sphinx/ext/napoleon/docstring.py
index 9ee3b056..d99245c9 100644
--- a/sphinx/ext/napoleon/docstring.py
+++ b/sphinx/ext/napoleon/docstring.py
@@ -11,6 +11,8 @@
     :license: BSD, see LICENSE for details.
 """
 
+import collections
+import inspect
 import re
 import sys
 from sphinx.ext.napoleon.iterators import modify_iter
@@ -94,9 +96,21 @@ class GoogleDocstring(object):
                  obj=None, options=None):
         self._config = config
         self._app = app
+
         if not self._config:
             from sphinx.ext.napoleon import Config
             self._config = self._app and self._app.config or Config()
+
+        if not what:
+            if inspect.isclass(obj):
+                what = 'class'
+            elif inspect.ismodule(obj):
+                what = 'module'
+            elif isinstance(obj, collections.Callable):
+                what = 'function'
+            else:
+                what = 'object'
+
         self._what = what
         self._name = name
         self._obj = obj
@@ -724,3 +738,112 @@ class NumpyDocstring(GoogleDocstring):
                     if section.startswith(directive_section):
                         return True
         return False
+
+    _name_rgx = re.compile(r"^\s*(:(?P<role>\w+):`(?P<name>[a-zA-Z0-9_.-]+)`|"
+                           r" (?P<name2>[a-zA-Z0-9_.-]+))\s*", re.X)
+
+    def _parse_see_also_section(self, section):
+        """
+        Derived from the NumpyDoc implementation of _parse_see_also.
+
+        func_name : Descriptive text
+            continued text
+        another_func_name : Descriptive text
+        func_name1, func_name2, :meth:`func_name`, func_name3
+
+        """
+        content = self._consume_to_next_section()
+        items = []
+
+        def parse_item_name(text):
+            """Match ':role:`name`' or 'name'"""
+            m = self._name_rgx.match(text)
+            if m:
+                g = m.groups()
+                if g[1] is None:
+                    return g[3], None
+                else:
+                    return g[2], g[1]
+            raise ValueError("%s is not a item name" % text)
+
+        def push_item(name, rest):
+            if not name:
+                return
+            name, role = parse_item_name(name)
+            items.append((name, list(rest), role))
+            del rest[:]
+
+        current_func = None
+        rest = []
+
+        for line in content:
+            if not line.strip(): continue
+
+            m = self._name_rgx.match(line)
+            if m and line[m.end():].strip().startswith(':'):
+                push_item(current_func, rest)
+                current_func, line = line[:m.end()], line[m.end():]
+                rest = [line.split(':', 1)[1].strip()]
+                if not rest[0]:
+                    rest = []
+            elif not line.startswith(' '):
+                push_item(current_func, rest)
+                current_func = None
+                if ',' in line:
+                    for func in line.split(','):
+                        if func.strip():
+                            push_item(func, [])
+                elif line.strip():
+                    current_func = line
+            elif current_func is not None:
+                rest.append(line.strip())
+        push_item(current_func, rest)
+
+
+        if not items:
+            return []
+
+        roles = {
+            'method': 'meth',
+            'meth': 'meth',
+            'function': 'func',
+            'func': 'func',
+            'class': 'class',
+            'exception': 'exc',
+            'exc': 'exc',
+            'object': 'obj',
+            'obj': 'obj',
+            'module': 'mod',
+            'mod': 'mod',
+            'data': 'data',
+            'constant': 'const',
+            'const': 'const',
+            'attribute': 'attr',
+            'attr': 'attr'
+        }
+        if self._what is None:
+            func_role = 'obj'
+        else:
+            func_role = roles.get(self._what, '')
+        lines = []
+        last_had_desc = True
+        for func, desc, role in items:
+            if role:
+                link = ':%s:`%s`' % (role, func)
+            elif func_role:
+                link = ':%s:`%s`' % (func_role, func)
+            else:
+                link = "`%s`_" % func
+            if desc or last_had_desc:
+                lines += ['']
+                lines += [link]
+            else:
+                lines[-1] += ", %s" % link
+            if desc:
+                lines += self._indent([' '.join(desc)])
+                last_had_desc = True
+            else:
+                last_had_desc = False
+        lines += ['']
+
+        return self._format_admonition('seealso', lines)
diff --git a/tests/test_napoleon_docstring.py b/tests/test_napoleon_docstring.py
index 7d5e3ad8..61b9efe2 100644
--- a/tests/test_napoleon_docstring.py
+++ b/tests/test_napoleon_docstring.py
@@ -15,6 +15,12 @@ from sphinx.ext.napoleon import Config
 from sphinx.ext.napoleon.docstring import GoogleDocstring, NumpyDocstring
 from unittest import TestCase
 
+try:
+    # Python >=3.3
+    from unittest.mock import Mock
+except ImportError:
+    from mock import Mock
+
 
 class BaseDocstringTest(TestCase):
     pass
@@ -306,3 +312,50 @@ class NumpyDocstringTest(BaseDocstringTest):
             :type param1: MyClass instance
             """)
         self.assertEqual(expected, actual)
+
+    def test_see_also_refs(self):
+        docstring = """
+            numpy.multivariate_normal(mean, cov, shape=None, spam=None)
+
+            See Also
+            --------
+            some, other, funcs
+            otherfunc : relationship
+
+            """
+
+        actual = str(NumpyDocstring(textwrap.dedent(docstring)))
+
+        expected = """
+numpy.multivariate_normal(mean, cov, shape=None, spam=None)
+
+.. seealso::
+\n   :obj:`some`, :obj:`other`, :obj:`funcs`
+   \n   :obj:`otherfunc`
+       relationship
+"""
+        self.assertEqual(expected, actual)
+
+        docstring = """
+            numpy.multivariate_normal(mean, cov, shape=None, spam=None)
+
+            See Also
+            --------
+            some, other, funcs
+            otherfunc : relationship
+
+            """
+
+        config = Config()
+        app = Mock()
+        actual = str(NumpyDocstring(textwrap.dedent(docstring), config, app, "method"))
+
+        expected = """
+numpy.multivariate_normal(mean, cov, shape=None, spam=None)
+
+.. seealso::
+\n   :meth:`some`, :meth:`other`, :meth:`funcs`
+   \n   :meth:`otherfunc`
+       relationship
+"""
+        self.assertEqual(expected, actual)