diff --git a/sphinx/ext/napoleon/docstring.py b/sphinx/ext/napoleon/docstring.py index f9db044f2..6e3aaeaf6 100644 --- a/sphinx/ext/napoleon/docstring.py +++ b/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, - 'warning': self._parse_warning_section, - 'warnings': self._parse_warning_section, + 'tip': partial(self._parse_admonition, 'tip'), + 'todo': partial(self._parse_admonition, 'todo'), + '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] - lines = self._consume_to_next_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) + # type (unicode) -> List[unicode] + return self._parse_admonition('seealso', section) def _parse_warns_section(self, section): # type: (unicode) -> List[unicode] diff --git a/tests/test_ext_napoleon_docstring.py b/tests/test_ext_napoleon_docstring.py index e06d39d10..3b921ea27 100644 --- a/tests/test_ext_napoleon_docstring.py +++ b/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,