Skip to content

Commit 999927b

Browse files
ChilippChilipp
authored
Merge pull request #42 from EpicWink/docstring-ensure-iterable
Default falsy 'get_doc' result to the empty-list
2 parents 6bc5815 + 3ab8843 commit 999927b

File tree

4 files changed

+112
-23
lines changed

4 files changed

+112
-23
lines changed

‎.github/workflows/python-app.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ jobs:
1515
strategy:
1616
matrix:
1717
python-version: [3.5, 3.6, 3.7, 3.8]
18-
sphinx-version: ["", "3.2.*", "3.1.*", "3.0.*", "2.4.*", "2.3.*", "2.2.*"]
18+
sphinx-version: ["", "3.5.*", "3.4.*", "3.2.*", "3.1.*", "3.0.*", "2.4.*", "2.3.*", "2.2.*"]
1919

2020
steps:
2121
- uses: actions/checkout@v2

‎autodocsumm/__init__.py‎

Lines changed: 15 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020

2121
from sphinx.ext.autodoc import (
2222
ClassDocumenter, ModuleDocumenter, ALL, PycodeError,
23-
ModuleAnalyzer, bool_option, AttributeDocumenter, DataDocumenter, Options,
23+
ModuleAnalyzer, AttributeDocumenter, DataDocumenter, Options,
2424
prepare_docstring)
2525
import sphinx.ext.autodoc as ad
2626

@@ -85,6 +85,10 @@ def list_option(option):
8585
return [s.strip() for s in option.split(";;")]
8686

8787

88+
def bool_option(*args):
89+
return "True"
90+
91+
8892
class AutosummaryDocumenter(object):
8993
"""Abstract class for for extending Documenter methods
9094
@@ -155,7 +159,7 @@ def get_grouped_documenters(self, all_members=False):
155159
self.env.temp_data['autodoc:class'] = self.objpath[0]
156160

157161
if not self.options.autosummary_force_inline:
158-
docstring = self.get_doc()
162+
docstring = self.get_doc() or []
159163
autodocsumm_directive = '.. auto%ssumm::' % self.objtype
160164
for s in chain.from_iterable(docstring):
161165
if autodocsumm_directive in s:
@@ -230,7 +234,10 @@ def get_grouped_documenters(self, all_members=False):
230234

231235
def add_autosummary(self):
232236
"""Add the autosammary table of this documenter."""
233-
if self.options.autosummary:
237+
if (
238+
self.options.get("autosummary")
239+
and not self.options.get("no-autosummary")
240+
):
234241

235242
grouped_documenters = self.get_grouped_documenters()
236243

@@ -296,8 +303,8 @@ def add_content(self, *args, **kwargs):
296303

297304
self.add_autosummary()
298305

299-
if self.options.autosummary_no_nesting:
300-
self.options.autosummary = False
306+
if self.options.get("autosummary-no-nesting"):
307+
self.options["no-autosummary"] = "True"
301308

302309

303310
class AutoSummClassDocumenter(ClassDocumenter, AutosummaryDocumenter):
@@ -524,10 +531,10 @@ def run(self):
524531
objtype = self.name[4:-4] # strip prefix (auto-) and suffix (-summ).
525532
doccls = self.env.app.registry.documenters[objtype]
526533

527-
self.options['autosummary-force-inline'] = True
528-
self.options['autosummary'] = True
534+
self.options['autosummary-force-inline'] = "True"
535+
self.options['autosummary'] = "True"
529536
if 'no-members' not in self.options:
530-
self.options['members'] = True
537+
self.options['members'] = ""
531538

532539
# process the options with the selected documenter's option_spec
533540
try:

‎tests/sphinx_supp/conf.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,8 @@
2020
'dummy.large_data', 'dummy.TestClass.small_data',
2121
'dummy_title.large_data', 'dummy_title.TestClass.small_data']
2222

23+
autodoc_typehints = "description"
24+
2325
autodata_content = 'both'
2426

2527

‎tests/test_autodocsumm.py‎

Lines changed: 94 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -49,11 +49,43 @@ def test_module(self, app, status, warning):
4949
self.assertIn('<span class="pre">large_data</span>', html)
5050
self.assertIn('<span class="pre">small_data</span>', html)
5151

52-
self.assertNotIn('Should be skipped', html)
53-
self.assertIn('Should be included', html)
54-
55-
self.assertNotIn('Should also be skipped', html)
56-
self.assertIn('Should also be included', html)
52+
try:
53+
self.assertIn('Should be included', html)
54+
except AssertionError: # sphinx>=3.5
55+
self.assertIn(
56+
'<span class="pre">\'Should</span> '
57+
'<span class="pre">be</span> '
58+
'<span class="pre">included\'</span>',
59+
html
60+
)
61+
self.assertNotIn(
62+
'<span class="pre">\'Should</span> '
63+
'<span class="pre">be</span> '
64+
'<span class="pre">skipped\'</span>',
65+
html
66+
)
67+
else:
68+
self.assertNotIn('Should be skipped', html)
69+
70+
try:
71+
self.assertIn('Should also be included', html)
72+
except AssertionError: # sphinx>=3.5
73+
self.assertIn(
74+
'<span class="pre">\'Should</span> '
75+
'<span class="pre">also</span> '
76+
'<span class="pre">be</span> '
77+
'<span class="pre">included\'</span>',
78+
html
79+
)
80+
self.assertNotIn(
81+
'<span class="pre">\'Should</span> '
82+
'<span class="pre">also</span> '
83+
'<span class="pre">be</span> '
84+
'<span class="pre">skipped\'</span>',
85+
html
86+
)
87+
else:
88+
self.assertNotIn('Should also be skipped', html)
5789

5890
@with_app(buildername='html', srcdir=sphinx_supp,
5991
copy_srcdir_to_tmpdir=True)
@@ -69,8 +101,18 @@ def test_module_no_nesting(self, app, status, warning):
69101
self.assertIn('<span class="pre">small_data</span>', html)
70102

71103
# test that elements of TestClass are not autosummarized, since nesting is disabled.
72-
self.assertNotIn('<span class="pre">test_method</span>', html)
73-
self.assertNotIn('<span class="pre">test_attr</span>', html)
104+
try:
105+
self.assertNotIn('<span class="pre">test_method</span>', html)
106+
self.assertNotIn('<span class="pre">test_attr</span>', html)
107+
except AssertionError: # sphinx>=3.5
108+
self.assertEqual(
109+
len(re.findall('<span class="pre">test_method</span>', html)),
110+
1,
111+
)
112+
self.assertEqual(
113+
len(re.findall('<span class="pre">test_attr</span>', html)),
114+
1,
115+
)
74116

75117
# test the members are still displayed
76118
self.assertIn('<dt id="dummy.Class_CallTest">', html)
@@ -106,12 +148,42 @@ def test_module_with_title(self, app, status, warning):
106148
# test whether the data is shown correctly
107149
self.assertIn('<span class="pre">large_data</span>', html)
108150
self.assertIn('<span class="pre">small_data</span>', html)
109-
110-
self.assertNotIn('Should be skipped', html)
111-
self.assertIn('Should be included', html)
112-
113-
self.assertNotIn('Should also be skipped', html)
114-
self.assertIn('Should also be included', html)
151+
try:
152+
self.assertIn('Should be included', html)
153+
except AssertionError: # sphinx>=3.5
154+
self.assertIn(
155+
'<span class="pre">\'Should</span> '
156+
'<span class="pre">be</span> '
157+
'<span class="pre">included\'</span>',
158+
html
159+
)
160+
self.assertNotIn(
161+
'<span class="pre">\'Should</span> '
162+
'<span class="pre">be</span> '
163+
'<span class="pre">skipped\'</span>',
164+
html
165+
)
166+
else:
167+
self.assertNotIn('Should be skipped', html)
168+
try:
169+
self.assertIn('Should also be included', html)
170+
except AssertionError: # sphinx>=3.5
171+
self.assertIn(
172+
'<span class="pre">\'Should</span> '
173+
'<span class="pre">also</span> '
174+
'<span class="pre">be</span> '
175+
'<span class="pre">included\'</span>',
176+
html
177+
)
178+
self.assertNotIn(
179+
'<span class="pre">\'Should</span> '
180+
'<span class="pre">also</span> '
181+
'<span class="pre">be</span> '
182+
'<span class="pre">skipped\'</span>',
183+
html
184+
)
185+
else:
186+
self.assertNotIn('Should also be skipped', html)
115187

116188
@with_app(buildername='html', srcdir=sphinx_supp,
117189
copy_srcdir_to_tmpdir=True)
@@ -146,7 +218,15 @@ def test_class(self, app, status, warning):
146218
self.assertIn('<span class="pre">small_data</span>', html)
147219

148220
self.assertNotIn('Should be skipped', html)
149-
self.assertIn('Should be included', html)
221+
try:
222+
self.assertIn('Should be included', html)
223+
except AssertionError: # sphinx>=3.5
224+
self.assertIn(
225+
'<span class="pre">\'Should</span> '
226+
'<span class="pre">be</span> '
227+
'<span class="pre">included\'</span>',
228+
html
229+
)
150230

151231
self.assertIn('DummySection', html)
152232
self.assertTrue(in_between(

0 commit comments

Comments
 (0)