SphinxDocString class in new numpy doc framework
I guess this question is mostly for Stefan... but I am trying to port the scikits.timeseries module wiki documentation into a sphinx framework, and also trying to follow the numpy doc string standards (which can't be parsed directly by sphinx), so I'm trying to use the SphinxDocString class in docscrape_sphinx.py to pre-process the doc strings. However, the doc strings do not seem to be getting processed correctly. I didn't dig deep into the issue, but I thought I'd ask first before I go any further in case I am approaching this incorrectly all together. If I try to process the numpy.swapaxes docstring for example, I get the following output (note the formatting of the parameters):
print SphinxDocString(np.swapaxes.__doc__)
Return a view of array a with axis1 and axis2 interchanged. **Parameters** `````````````` **a** : array_like Input array. axis1 : int First axis. axis2 : int Second axis. **Examples** ```````````` >>> x = np.array([[1,2,3]]) >>> np.swapaxes(x,0,1) array([[1], [2], [3]]) >>> x = np.array([[[0,1],[2,3]],[[4,5],[6,7]]]) >>> x array([[[0, 1], [2, 3]], [[4, 5], [6, 7]]]) >>> np.swapaxes(x,0,2) array([[[0, 4], [2, 6]], [[1, 5], [3, 7]]]) ================================================================ I don't know if the SphinxDocString class is even ready for use yet or not, but this didn't look right to me. The other thing I was wondering is if anyone knows how to pre-process doc strings on the fly such that you can mix them in with your .rst files similar to how the autodoc sphinx extension works (rather than just pre-generating a big dump of all the doc strings into a single .rst file). This is probably a question more for the sphinx mailing list, but I thought I'd ask while I'm on the topic in case anyone has any quick tricks they can share. Thanks, - Matt -- View this message in context: http://www.nabble.com/SphinxDocString-class-in-new-numpy-doc-framework-tp181... Sent from the Numpy-discussion mailing list archive at Nabble.com.
Matt, David Huard and myself have also been working on that. So far, we have a set of directives (numpyxxx, where xxx is function, attribute, method...) that satisfy the numpy standard and can be processed by sphinx. We also have the equivalent autodirectives. https://code.launchpad.net/~david-huard/scipy/numpydoc https://code.launchpad.net/~pierregm/scipy/numpydocs So far, we focused on making sure that the numpy standard was satisfied. I haven't tried to mix numpy standard and additional rst directives, I'll try to check that some time this week. Let me know how it goes.
Hi Matt
The docstring for ``np.swapaxes`` is broken -- notice the indent after
the first line. If you remove that, things should be fine:
In [31]: d = np.swapaxes.__doc__
In [32]: d = d.split('\n')
In [33]: d[0] = ' Return a view of an array a with axis1 and axis2
interchanged.'
In [34]: print SphinxDocString('\n'.join(d))
Return a view of an array a with axis1 and axis2 interchanged.
**Parameters**
``````````````
**a** : array_like
Input array.
etc.
Cheers
Stéfan
2008/6/30 Matt Knox
I guess this question is mostly for Stefan... but I am trying to port the scikits.timeseries module wiki documentation into a sphinx framework, and also trying to follow the numpy doc string standards (which can't be parsed directly by sphinx), so I'm trying to use the SphinxDocString class in docscrape_sphinx.py to pre-process the doc strings. However, the doc strings do not seem to be getting processed correctly. I didn't dig deep into the issue, but I thought I'd ask first before I go any further in case I am approaching this incorrectly all together.
If I try to process the numpy.swapaxes docstring for example, I get the following output (note the formatting of the parameters):
print SphinxDocString(np.swapaxes.__doc__)
participants (3)
-
Matt Knox -
Pierre GM -
Stéfan van der Walt