1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
# ----------------------------------------------------------------------------
# Copyright (c) 2013--, scikit-bio development team.
#
# Distributed under the terms of the Modified BSD License.
#
# The full license is in the file LICENSE.txt, distributed with this software.
# ----------------------------------------------------------------------------
import unittest
from skbio.util._docstring import (
_note_into_doc,
_note_into_doc_param,
)
class TestDocstring(unittest.TestCase):
def setUp(self):
self.docstring = """An example function.
Here is an example function with a typical docstring.
Parameters
----------
param1 : int
The first parameter.
param2 : str, optional
The second parameter.
Returns
-------
float
The return value.
"""
def test_note_into_doc(self):
note = ".. note:: This is a note.\n"
# normal case
obs = _note_into_doc(note, self.docstring)
exp = """An example function.
.. note:: This is a note.
Here is an example function with a typical docstring.
"""
self.assertIn(exp, obs)
# no docstring
obs = _note_into_doc(note, "")
self.assertEqual(obs, note)
# single-line docstring
obs = _note_into_doc(note, "Hello!")
self.assertEqual(obs, f"Hello!\n\n{note}")
obs = _note_into_doc(note, "Hello!\n")
self.assertEqual(obs, f"Hello!\n\n{note}")
# single-paragraph docstring
obs = _note_into_doc(note, "Hello!\nHello!\nHello!\n")
self.assertEqual(obs, f"Hello!\nHello!\nHello!\n\n{note}")
# single-paragraph docstring with indentation
doc = """Hello! I am the
header paragraph.
"""
obs = _note_into_doc(note, doc)
exp = """Hello! I am the
header paragraph.
.. note:: This is a note.
"""
self.assertEqual(obs, exp)
def test_note_into_doc_param(self):
note = ".. note:: This is a note."
# first parameter
obs = _note_into_doc_param(note, self.docstring, "param1")
exp = """
param1 : int
The first parameter.
.. note:: This is a note.
param2 : str, optional
"""
self.assertIn(exp, obs)
# last parameter
obs = _note_into_doc_param(note, self.docstring, "param2")
exp = """
param2 : str, optional
The second parameter.
.. note:: This is a note.
Returns
"""
self.assertIn(exp, obs)
# missing parameter
with self.assertRaises(ValueError):
_note_into_doc_param(note, self.docstring, "param3")
# no more section
doc = self.docstring[:self.docstring.find("Returns")]
obs = _note_into_doc_param(note, doc, "param2")
exp = """
param2 : str, optional
The second parameter.
.. note:: This is a note.
"""
self.assertTrue(obs.endswith(exp))
if __name__ == '__main__':
unittest.main()
|
