ENH Only print the index if it is necessary. (#187)

Author: hmaarrfk

numpydoc/docscrape.py

@@ -464,12 +464,20 @@ def _str_see_also(self, func_role):
     def _str_index(self):
         idx = self['index']
         out = []
-        out += ['.. index:: %s' % idx.get('default', '')]
+        output_index = False
+        default_index = idx.get('default', '')
+        if default_index:
+            output_index = True
+        out += ['.. index:: %s' % default_index]
         for section, references in idx.items():
             if section == 'default':
                 continue
+            output_index = True
             out += ['   :%s: %s' % (section, ', '.join(references))]
-        return out
+        if output_index:
+            return out
+        else:
+            return ''
 
     def __str__(self, func_role=''):
         out = []

numpydoc/tests/test_docscrape.py

@@ -468,6 +468,22 @@ def test_yield_str():
 .. index:: """)
 
 
+def test_no_index_in_str():
+    assert "index" not in str(NumpyDocString("""Test idx
+
+    """))
+
+    assert "index" in str(NumpyDocString("""Test idx
+
+    .. index :: random
+    """))
+
+    assert "index" in str(NumpyDocString("""Test idx
+
+    .. index ::
+        foo
+    """))
+
 def test_sphinx_str():
     sphinx_doc = SphinxDocString(doc_txt)
     line_by_line_compare(str(sphinx_doc),