Browse files

sphinxext: fix Other Parameters section parsing in docscrape

  • Loading branch information...
1 parent 75cebc1 commit 4510c4a81185eed7e144f75ec5121f80bc924a6e @pv pv committed Oct 1, 2010
Showing with 79 additions and 7 deletions.
  1. +4 −3 doc/sphinxext/docscrape.py
  2. +2 −1 doc/sphinxext/docscrape_sphinx.py
  3. +73 −3 doc/sphinxext/tests/test_docscrape.py
View
7 doc/sphinxext/docscrape.py
@@ -284,8 +284,8 @@ 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', 'Attributes', 'Methods',
- 'Returns', 'Raises', 'Warns'):
+ if section in ('Parameters', 'Returns', 'Raises', 'Warns',
+ 'Other Parameters', 'Attributes', 'Methods'):
self[section] = self._parse_param_list(content)
elif section.startswith('.. index::'):
self['index'] = self._parse_index(section, content)
@@ -381,7 +381,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','Raises'):
+ for param_list in ('Parameters', 'Returns', 'Other Parameters',
+ 'Raises', 'Warns'):
out += self._str_param_list(param_list)
out += self._str_section('Warnings')
out += self._str_see_also(func_role)
View
3 doc/sphinxext/docscrape_sphinx.py
@@ -178,7 +178,8 @@ def __str__(self, indent=0, func_role="obj"):
out += self._str_index() + ['']
out += self._str_summary()
out += self._str_extended_summary()
- for param_list in ('Parameters', 'Returns', 'Raises'):
+ for param_list in ('Parameters', 'Returns', 'Other Parameters',
+ 'Raises', 'Warns'):
out += self._str_param_list(param_list)
out += self._str_warnings()
out += self._str_see_also(func_role)
View
76 doc/sphinxext/tests/test_docscrape.py
@@ -8,7 +8,7 @@
from nose.tools import *
doc_txt = '''\
- numpy.multivariate_normal(mean, cov, shape=None)
+ numpy.multivariate_normal(mean, cov, shape=None, spam=None)
Draw values from a multivariate normal distribution with specified
mean and covariance.
@@ -42,6 +42,21 @@
In other words, each entry ``out[i,j,...,:]`` is an N-dimensional
value drawn from the distribution.
+ Other Parameters
+ ----------------
+ spam : parrot
+ A parrot off its mortal coil.
+
+ Raises
+ ------
+ RuntimeError
+ Some error
+
+ Warns
+ -----
+ RuntimeWarning
+ Some warning
+
Warnings
--------
Certain warnings apply.
@@ -102,7 +117,7 @@
def test_signature():
assert doc['Signature'].startswith('numpy.multivariate_normal(')
- assert doc['Signature'].endswith('shape=None)')
+ assert doc['Signature'].endswith('spam=None)')
def test_summary():
assert doc['Summary'][0].startswith('Draw values')
@@ -120,6 +135,13 @@ def test_parameters():
assert desc[0].startswith('Covariance matrix')
assert doc['Parameters'][0][-1][-2] == ' (1+2+3)/3'
+def test_other_parameters():
+ assert_equal(len(doc['Other Parameters']), 1)
+ assert_equal([n for n,_,_ in doc['Other Parameters']], ['spam'])
+ arg, arg_type, desc = doc['Other Parameters'][0]
+ assert_equal(arg_type, 'parrot')
+ assert desc[0].startswith('A parrot off its mortal coil')
+
def test_returns():
assert_equal(len(doc['Returns']), 1)
arg, arg_type, desc = doc['Returns'][0]
@@ -157,7 +179,7 @@ def non_blank_line_by_line_compare(a,b):
(n,line,b[n]))
def test_str():
non_blank_line_by_line_compare(str(doc),
-"""numpy.multivariate_normal(mean, cov, shape=None)
+"""numpy.multivariate_normal(mean, cov, shape=None, spam=None)
Draw values from a multivariate normal distribution with specified
mean and covariance.
@@ -191,6 +213,21 @@ def test_str():
In other words, each entry ``out[i,j,...,:]`` is an N-dimensional
value drawn from the distribution.
+Other Parameters
+----------------
+spam : parrot
+ A parrot off its mortal coil.
+
+Raises
+------
+RuntimeError :
+ Some error
+
+Warns
+-----
+RuntimeWarning :
+ Some warning
+
Warnings
--------
Certain warnings apply.
@@ -291,6 +328,24 @@ def test_sphinx_str():
In other words, each entry ``out[i,j,...,:]`` is an N-dimensional
value drawn from the distribution.
+:Other Parameters:
+
+ **spam** : parrot
+
+ A parrot off its mortal coil.
+
+:Raises:
+
+ **RuntimeError** :
+
+ Some error
+
+:Warns:
+
+ **RuntimeWarning** :
+
+ Some warning
+
.. warning::
Certain warnings apply.
@@ -390,6 +445,10 @@ def test_empty_extended_summary():
LinAlgException
If array is singular.
+ Warns
+ -----
+ SomeWarning
+ If needed
""")
def test_raises():
@@ -398,6 +457,12 @@ def test_raises():
assert_equal(name,'LinAlgException')
assert_equal(desc,['If array is singular.'])
+def test_warns():
+ assert_equal(len(doc5['Warns']), 1)
+ name,_,desc = doc5['Warns'][0]
+ assert_equal(name,'SomeWarning')
+ assert_equal(desc,['If needed'])
+
def test_see_also():
doc6 = NumpyDocString(
"""
@@ -543,3 +608,8 @@ def ham(self, c, d):
if cls is SphinxClassDoc:
assert '.. autosummary::' in str(doc), str(doc)
+
+if __name__ == "__main__":
+ import nose
+ nose.run()
+

0 comments on commit 4510c4a

Please sign in to comment.