IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Implement missing napoleon admonitions

Browse Source
This commit is contained in:
Martin Larralde 2018-02-13 17:38:44 +01:00
parent d315f9e251
commit 4d7c90d857
2 changed files with 98 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
sphinx/ext/napoleon/docstring.py
View File

@ -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]

79
tests/test_ext_napoleon_docstring.py
View File

@ -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,