Implement missing napoleon admonitions

sphinx/ext/napoleon/docstring.py

@@ -14,6 +14,7 @@
 import collections
 import inspect
 import re
+from functools import partial
 
 from six import string_types, u
 from six.moves import range
@@ -140,13 +141,19 @@ class GoogleDocstring(UnicodeMixin):
             self._sections = {
                 'args': self._parse_parameters_section,
                 'arguments': self._parse_parameters_section,
+                'attention': partial(self._parse_admonition, 'attention'),
                 'attributes': self._parse_attributes_section,
+                'caution': partial(self._parse_admonition, 'caution'),
+                'danger': partial(self._parse_admonition, 'danger'),
+                'error': partial(self._parse_admonition, 'error'),
                 'example': self._parse_examples_section,
                 'examples': self._parse_examples_section,
+                'hint': partial(self._parse_admonition, 'hint'),
+                'important': partial(self._parse_admonition, 'important'),
                 'keyword args': self._parse_keyword_arguments_section,
                 'keyword arguments': self._parse_keyword_arguments_section,
                 'methods': self._parse_methods_section,
-                'note': self._parse_note_section,
+                'note': partial(self._parse_admonition, 'note'),
                 'notes': self._parse_notes_section,
                 'other parameters': self._parse_other_parameters_section,
                 'parameters': self._parse_parameters_section,
@@ -155,9 +162,10 @@ class GoogleDocstring(UnicodeMixin):
                 'raises': self._parse_raises_section,
                 'references': self._parse_references_section,
                 'see also': self._parse_see_also_section,
-                'todo': self._parse_todo_section,
+                'tip': partial(self._parse_admonition, 'tip'),
-                'warning': self._parse_warning_section,
+                'todo': partial(self._parse_admonition, 'todo'),
-                'warnings': self._parse_warning_section,
+                'warning': partial(self._parse_admonition, 'warning'),
+                'warnings': partial(self._parse_admonition, 'warning'),
                 'warns': self._parse_warns_section,
                 'yield': self._parse_yields_section,
                 'yields': self._parse_yields_section,
@@ -550,6 +558,11 @@ class GoogleDocstring(UnicodeMixin):
                     lines = self._consume_to_next_section()
             self._parsed_lines.extend(lines)
 
+    def _parse_admonition(self, admonition, section):
+        # type (unicode, unicode) -> List[unicode]
+        lines = self._consume_to_next_section()
+        return self._format_admonition(admonition, lines)
+
     def _parse_attribute_docstring(self):
         # type: () -> List[unicode]
         _type, _desc = self._consume_inline_attribute()
@@ -627,11 +640,6 @@ class GoogleDocstring(UnicodeMixin):
             lines.append('')
         return lines
 
-    def _parse_note_section(self, section):
-        # type: (unicode) -> List[unicode]
-        lines = self._consume_to_next_section()
-        return self._format_admonition('note', lines)
-
     def _parse_notes_section(self, section):
         # type: (unicode) -> List[unicode]
         use_admonition = self._config.napoleon_use_admonition_for_notes
@@ -723,19 +731,8 @@ class GoogleDocstring(UnicodeMixin):
         return lines
 
     def _parse_see_also_section(self, section):
-        # type: (unicode) -> List[unicode]
+        # type (unicode) -> List[unicode]
-        lines = self._consume_to_next_section()
+        return self._parse_admonition('seealso', section)
-        return self._format_admonition('seealso', lines)
-
-    def _parse_todo_section(self, section):
-        # type: (unicode) -> List[unicode]
-        lines = self._consume_to_next_section()
-        return self._format_admonition('todo', lines)
-
-    def _parse_warning_section(self, section):
-        # type: (unicode) -> List[unicode]
-        lines = self._consume_to_next_section()
-        return self._format_admonition('warning', lines)
 
     def _parse_warns_section(self, section):
         # type: (unicode) -> List[unicode]

tests/test_ext_napoleon_docstring.py

@@ -272,6 +272,45 @@ class GoogleDocstringTest(BaseDocstringTest):
         """
     )]
 
+    def test_sphinx_admonitions(self):
+        admonition_map = {
+            'Attention': 'attention',
+            'Caution': 'caution',
+            'Danger': 'danger',
+            'Error': 'error',
+            'Hint': 'hint',
+            'Important': 'important',
+            'Note': 'note',
+            'Tip': 'tip',
+            'Todo': 'todo',
+            'Warning': 'warning',
+            'Warnings': 'warning',
+        }
+        config = Config()
+        for section, admonition in admonition_map.items():
+            # Multiline
+            actual = str(GoogleDocstring(("{}:\n"
+                      "    this is the first line\n"
+                      "\n"
+                      "    and this is the second line\n"
+                      ).format(section), config))
+            expect = (".. {}::\n"
+                      "\n"
+                      "   this is the first line\n"
+                      "   \n"
+                      "   and this is the second line\n"
+                      ).format(admonition)
+            self.assertEqual(expect, actual)
+
+            # Single line
+            actual = str(GoogleDocstring(("{}:\n"
+                      "    this is a single line\n"
+                      ).format(section), config))
+            expect = (".. {}:: this is a single line\n"
+                      ).format(admonition)
+            self.assertEqual(expect, actual)
+
+
     def test_docstrings(self):
         config = Config(
             napoleon_use_param=False,
@@ -1081,6 +1120,46 @@ class NumpyDocstringTest(BaseDocstringTest):
         """
     )]
 
+    def test_sphinx_admonitions(self):
+        admonition_map = {
+            'Attention': 'attention',
+            'Caution': 'caution',
+            'Danger': 'danger',
+            'Error': 'error',
+            'Hint': 'hint',
+            'Important': 'important',
+            'Note': 'note',
+            'Tip': 'tip',
+            'Todo': 'todo',
+            'Warning': 'warning',
+            'Warnings': 'warning',
+        }
+        config = Config()
+        for section, admonition in admonition_map.items():
+            # Multiline
+            actual = str(NumpyDocstring(("{}\n"
+                      "{}\n"
+                      "    this is the first line\n"
+                      "\n"
+                      "    and this is the second line\n"
+                      ).format(section, '-'*len(section)), config))
+            expect = (".. {}::\n"
+                      "\n"
+                      "   this is the first line\n"
+                      "   \n"
+                      "   and this is the second line\n"
+                      ).format(admonition)
+            self.assertEqual(expect, actual)
+
+            # Single line
+            actual = str(NumpyDocstring(("{}\n"
+                      "{}\n"
+                      "    this is a single line\n"
+                      ).format(section, '-'*len(section)), config))
+            expect = (".. {}:: this is a single line\n"
+                      ).format(admonition)
+            self.assertEqual(expect, actual)
+
     def test_docstrings(self):
         config = Config(
             napoleon_use_param=False,