From b6af82510e1be001accea2d4840ff16f960a0809 Mon Sep 17 00:00:00 2001 From: chebee7i Date: Sat, 19 Jul 2014 14:04:04 -0500 Subject: [PATCH 1/9] Support Yields section. --- numpydoc/docscrape.py | 1 + 1 file changed, 1 insertion(+) diff --git a/numpydoc/docscrape.py b/numpydoc/docscrape.py index 2b1719db5c96b..330612fdc7421 100644 --- a/numpydoc/docscrape.py +++ b/numpydoc/docscrape.py @@ -97,6 +97,7 @@ def __init__(self, docstring, config={}): 'Extended Summary': [], 'Parameters': [], 'Returns': [], + 'Yields': [], 'Raises': [], 'Warns': [], 'Other Parameters': [], From 246b4404631015f14505cb19ccab2e7d70abbd68 Mon Sep 17 00:00:00 2001 From: chebee7i Date: Sat, 19 Jul 2014 14:05:44 -0500 Subject: [PATCH 2/9] Support Yields section in traitsdoc too. --- numpydoc/traitsdoc.py | 1 + 1 file changed, 1 insertion(+) diff --git a/numpydoc/traitsdoc.py b/numpydoc/traitsdoc.py index 596c54eb389a3..dac39ae7f3de4 100644 --- a/numpydoc/traitsdoc.py +++ b/numpydoc/traitsdoc.py @@ -61,6 +61,7 @@ def __init__(self, cls, modulename='', func_doc=SphinxFunctionDoc): 'Extended Summary': [], 'Parameters': [], 'Returns': [], + 'Yields': [], 'Raises': [], 'Warns': [], 'Other Parameters': [], From 8f0bef9ce337a697c2785fcf901c4e9304114327 Mon Sep 17 00:00:00 2001 From: chebee7i Date: Sun, 11 Jan 2015 12:04:40 -0600 Subject: [PATCH 3/9] Add unit test for Yields section. --- numpydoc/docscrape.py | 5 +++-- numpydoc/tests/test_docscrape.py | 23 +++++++++++++++++++++++ 2 files changed, 26 insertions(+), 2 deletions(-) diff --git a/numpydoc/docscrape.py b/numpydoc/docscrape.py index 330612fdc7421..327f1abaecea4 100644 --- a/numpydoc/docscrape.py +++ b/numpydoc/docscrape.py @@ -292,8 +292,9 @@ def _parse(self): for (section,content) in self._read_sections(): if not section.startswith('..'): section = ' '.join([s.capitalize() for s in section.split(' ')]) - if section in ('Parameters', 'Returns', 'Raises', 'Warns', - 'Other Parameters', 'Attributes', 'Methods'): + if section in ('Parameters', 'Returns', 'Yields', 'Raises', + 'Warns', 'Other Parameters', 'Attributes', + 'Methods'): self[section] = self._parse_param_list(content) elif section.startswith('.. index::'): self['index'] = self._parse_index(section, content) diff --git a/numpydoc/tests/test_docscrape.py b/numpydoc/tests/test_docscrape.py index b682504e1618f..ad5d5668a44a2 100644 --- a/numpydoc/tests/test_docscrape.py +++ b/numpydoc/tests/test_docscrape.py @@ -164,6 +164,29 @@ def test_returns(): assert desc[0].startswith('This is not a real') assert desc[-1].endswith('anonymous return values.') +def test_yields(): + doc_text = """ +Test generator + +Yields +------ +a : int + The number of apples. +b : int + The number of bananas. + +""" + doc = NumpyDocString(doc_text) + section = doc['Yields'] + print(section) + assert_equal(len(section), 2) + truth = [('a', 'apples.'), ('b', 'bananas.')] + for (arg, arg_type, desc), (arg_true, ending) in zip(section, truth): + assert_equal(arg, arg_true) + assert_equal(arg_type, 'int') + assert desc[0].startswith('The number of') + assert desc[0].endswith(ending) + def test_notes(): assert doc['Notes'][0].startswith('Instead') assert doc['Notes'][-1].endswith('definite.') From 95c287910577af2a4f4f8911cafde3a9708cc3c1 Mon Sep 17 00:00:00 2001 From: chebee7i Date: Sun, 11 Jan 2015 12:29:19 -0600 Subject: [PATCH 4/9] Add support for Yields for sphinx strings as well. --- numpydoc/docscrape_sphinx.py | 17 +++++++++++++++++ numpydoc/traitsdoc.py | 2 +- 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/numpydoc/docscrape_sphinx.py b/numpydoc/docscrape_sphinx.py index cdc2a37d17174..3f7c288583fb7 100644 --- a/numpydoc/docscrape_sphinx.py +++ b/numpydoc/docscrape_sphinx.py @@ -63,6 +63,23 @@ def _str_returns(self): out += [''] return out + def _str_yields(self): + out = [] + if self['Yields']: + out += self._str_field_list('Yields') + out += [''] + for param, param_type, desc in self['Yields']: + if param_type: + out += self._str_indent(['**%s** : %s' % (param.strip(), + param_type)]) + else: + out += self._str_indent([param.strip()]) + if desc: + out += [''] + out += self._str_indent(desc, 8) + out += [''] + return out + def _str_param_list(self, name): out = [] if self[name]: diff --git a/numpydoc/traitsdoc.py b/numpydoc/traitsdoc.py index dac39ae7f3de4..2468565a6ca1e 100644 --- a/numpydoc/traitsdoc.py +++ b/numpydoc/traitsdoc.py @@ -90,7 +90,7 @@ def __str__(self, indent=0, func_role="func"): out += self._str_summary() out += self._str_extended_summary() for param_list in ('Parameters', 'Traits', 'Methods', - 'Returns','Raises'): + 'Returns', 'Yields', 'Raises'): out += self._str_param_list(param_list) out += self._str_see_also("obj") out += self._str_section('Notes') From ddb5632673540890ae5199d85ab6138a56255210 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Sun, 11 Jan 2015 16:13:43 -0500 Subject: [PATCH 5/9] ENH : simplify handling of Yield section --- numpydoc/docscrape.py | 4 ++-- numpydoc/docscrape_sphinx.py | 18 +----------------- 2 files changed, 3 insertions(+), 19 deletions(-) diff --git a/numpydoc/docscrape.py b/numpydoc/docscrape.py index 327f1abaecea4..572145ccdee4c 100644 --- a/numpydoc/docscrape.py +++ b/numpydoc/docscrape.py @@ -393,8 +393,8 @@ def __str__(self, func_role=''): out += self._str_signature() out += self._str_summary() out += self._str_extended_summary() - for param_list in ('Parameters', 'Returns', 'Other Parameters', - 'Raises', 'Warns'): + for param_list in ('Parameters', 'Returns', 'Yields', + 'Other Parameters', 'Raises', 'Warns'): out += self._str_param_list(param_list) out += self._str_section('Warnings') out += self._str_see_also(func_role) diff --git a/numpydoc/docscrape_sphinx.py b/numpydoc/docscrape_sphinx.py index 3f7c288583fb7..82076d02481cb 100644 --- a/numpydoc/docscrape_sphinx.py +++ b/numpydoc/docscrape_sphinx.py @@ -63,23 +63,6 @@ def _str_returns(self): out += [''] return out - def _str_yields(self): - out = [] - if self['Yields']: - out += self._str_field_list('Yields') - out += [''] - for param, param_type, desc in self['Yields']: - if param_type: - out += self._str_indent(['**%s** : %s' % (param.strip(), - param_type)]) - else: - out += self._str_indent([param.strip()]) - if desc: - out += [''] - out += self._str_indent(desc, 8) - out += [''] - return out - def _str_param_list(self, name): out = [] if self[name]: @@ -242,6 +225,7 @@ def __str__(self, indent=0, func_role="obj"): out += self._str_extended_summary() out += self._str_param_list('Parameters') out += self._str_returns() + out += self._str_param_list('Yields') for param_list in ('Other Parameters', 'Raises', 'Warns'): out += self._str_param_list(param_list) out += self._str_warnings() From def02e67112275384772dad07854f7b25b5f1a97 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Sun, 11 Jan 2015 16:15:25 -0500 Subject: [PATCH 6/9] TST : removed print statement --- numpydoc/tests/test_docscrape.py | 1 - 1 file changed, 1 deletion(-) diff --git a/numpydoc/tests/test_docscrape.py b/numpydoc/tests/test_docscrape.py index ad5d5668a44a2..9700ba9208a58 100644 --- a/numpydoc/tests/test_docscrape.py +++ b/numpydoc/tests/test_docscrape.py @@ -178,7 +178,6 @@ def test_yields(): """ doc = NumpyDocString(doc_text) section = doc['Yields'] - print(section) assert_equal(len(section), 2) truth = [('a', 'apples.'), ('b', 'bananas.')] for (arg, arg_type, desc), (arg_true, ending) in zip(section, truth): From b618d5263cecd8333f161ee395e903441330a83a Mon Sep 17 00:00:00 2001 From: chebee7i Date: Sun, 11 Jan 2015 16:19:53 -0600 Subject: [PATCH 7/9] ENH: Raise exception if docstring contains Returns and Yields. --- numpydoc/docscrape.py | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/numpydoc/docscrape.py b/numpydoc/docscrape.py index 572145ccdee4c..20c4883ec4818 100644 --- a/numpydoc/docscrape.py +++ b/numpydoc/docscrape.py @@ -289,7 +289,17 @@ def _parse(self): self._doc.reset() self._parse_summary() - for (section,content) in self._read_sections(): + sections = list(self._read_sections()) + section_names = set([section for section, content in sections]) + + has_returns = 'Returns' in section_names + has_yields = 'Yields' in section_names + # We could do more tests, but we are not. Arbitrarily. + if has_returns and has_yields: + msg = 'Docstring contains both a Returns and Yields section.' + raise ValueError(msg) + + for (section, content) in sections: if not section.startswith('..'): section = ' '.join([s.capitalize() for s in section.split(' ')]) if section in ('Parameters', 'Returns', 'Yields', 'Raises', From 8199426c12245a6e945b2328f0f696c080dd1e32 Mon Sep 17 00:00:00 2001 From: chebee7i Date: Sun, 11 Jan 2015 16:20:22 -0600 Subject: [PATCH 8/9] TST: More unit tests for the Yields section. --- numpydoc/docscrape_sphinx.py | 10 ++-- numpydoc/tests/test_docscrape.py | 83 ++++++++++++++++++++++++++++---- 2 files changed, 78 insertions(+), 15 deletions(-) diff --git a/numpydoc/docscrape_sphinx.py b/numpydoc/docscrape_sphinx.py index 82076d02481cb..5913c882d81b9 100644 --- a/numpydoc/docscrape_sphinx.py +++ b/numpydoc/docscrape_sphinx.py @@ -46,12 +46,12 @@ def _str_summary(self): def _str_extended_summary(self): return self['Extended Summary'] + [''] - def _str_returns(self): + def _str_returns(self, name='Returns'): out = [] - if self['Returns']: - out += self._str_field_list('Returns') + if self[name]: + out += self._str_field_list(name) out += [''] - for param, param_type, desc in self['Returns']: + for param, param_type, desc in self[name]: if param_type: out += self._str_indent(['**%s** : %s' % (param.strip(), param_type)]) @@ -225,7 +225,7 @@ def __str__(self, indent=0, func_role="obj"): out += self._str_extended_summary() out += self._str_param_list('Parameters') out += self._str_returns() - out += self._str_param_list('Yields') + out += self._str_returns('Yields') for param_list in ('Other Parameters', 'Raises', 'Warns'): out += self._str_param_list(param_list) out += self._str_warnings() diff --git a/numpydoc/tests/test_docscrape.py b/numpydoc/tests/test_docscrape.py index 9700ba9208a58..f1cfc48b2d60b 100644 --- a/numpydoc/tests/test_docscrape.py +++ b/numpydoc/tests/test_docscrape.py @@ -122,6 +122,20 @@ ''' doc = NumpyDocString(doc_txt) +doc_yields_txt = """ +Test generator + +Yields +------ +a : int + The number of apples. +b : int + The number of bananas. +int + The number of unknowns. +""" +doc_yields = NumpyDocString(doc_yields_txt) + def test_signature(): assert doc['Signature'].startswith('numpy.multivariate_normal(') @@ -165,8 +179,25 @@ def test_returns(): assert desc[-1].endswith('anonymous return values.') def test_yields(): + section = doc_yields['Yields'] + assert_equal(len(section), 3) + truth = [('a', 'int', 'apples.'), + ('b', 'int', 'bananas.'), + ('int', '', 'unknowns.')] + for (arg, arg_type, desc), (arg_, arg_type_, end) in zip(section, truth): + assert_equal(arg, arg_) + assert_equal(arg_type, arg_type_) + assert desc[0].startswith('The number of') + assert desc[0].endswith(end) + +def test_returnyield(): doc_text = """ -Test generator +Test having returns and yields. + +Returns +------- +int + The number of apples. Yields ------ @@ -176,15 +207,7 @@ def test_yields(): The number of bananas. """ - doc = NumpyDocString(doc_text) - section = doc['Yields'] - assert_equal(len(section), 2) - truth = [('a', 'apples.'), ('b', 'bananas.')] - for (arg, arg_type, desc), (arg_true, ending) in zip(section, truth): - assert_equal(arg, arg_true) - assert_equal(arg_type, 'int') - assert desc[0].startswith('The number of') - assert desc[0].endswith(ending) + assert_raises(ValueError, NumpyDocString, doc_text) def test_notes(): assert doc['Notes'][0].startswith('Instead') @@ -215,6 +238,9 @@ def non_blank_line_by_line_compare(a,b): "\n>>> %s\n<<< %s\n" % (n,line,b[n])) def test_str(): + # doc_txt has the order of Notes and See Also sections flipped. + # This should be handled automatically, and so, one thing this test does + # is to make sure that See Also precedes Notes in the output. non_blank_line_by_line_compare(str(doc), """numpy.multivariate_normal(mean, cov, shape=None, spam=None) @@ -324,6 +350,22 @@ def test_str(): :refguide: random;distributions, random;gauss""") +def test_yield_str(): + non_blank_line_by_line_compare(str(doc_yields), +"""Test generator + +Yields +------ +a : int + The number of apples. +b : int + The number of bananas. +int + The number of unknowns. + +.. index:: """) + + def test_sphinx_str(): sphinx_doc = SphinxDocString(doc_txt) non_blank_line_by_line_compare(str(sphinx_doc), @@ -449,6 +491,27 @@ def test_sphinx_str(): """) +def test_sphinx_yields_str(): + sphinx_doc = SphinxDocString(doc_yields_txt) + non_blank_line_by_line_compare(str(sphinx_doc), +"""Test generator + +:Yields: + + **a** : int + + The number of apples. + + **b** : int + + The number of bananas. + + int + + The number of unknowns. +""") + + doc2 = NumpyDocString(""" Returns array of indices of the maximum values of along the given axis. From 736951e14f4572de3d4db3b1255f5eec59e5f106 Mon Sep 17 00:00:00 2001 From: chebee7i Date: Sun, 11 Jan 2015 20:18:38 -0600 Subject: [PATCH 9/9] MAINT: More explicit call while building docstrings. --- numpydoc/docscrape_sphinx.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/numpydoc/docscrape_sphinx.py b/numpydoc/docscrape_sphinx.py index 5913c882d81b9..0464f11fdcec3 100644 --- a/numpydoc/docscrape_sphinx.py +++ b/numpydoc/docscrape_sphinx.py @@ -224,7 +224,7 @@ def __str__(self, indent=0, func_role="obj"): out += self._str_summary() out += self._str_extended_summary() out += self._str_param_list('Parameters') - out += self._str_returns() + out += self._str_returns('Returns') out += self._str_returns('Yields') for param_list in ('Other Parameters', 'Raises', 'Warns'): out += self._str_param_list(param_list)