Status of the doc format for scipy code ?
![](https://secure.gravatar.com/avatar/9820b5956634e5bbad7f4ed91a232822.jpg?s=120&d=mm&r=g)
Hi, I wanted to know what is the status of the doc format for scipy (http://projects.scipy.org/scipy/numpy/wiki/DocstringStandards) ? Is anything settled down ? cheers, David
![](https://secure.gravatar.com/avatar/af6c39d6943bd4b0e1fde23161e7bb8c.jpg?s=120&d=mm&r=g)
On Mon, Apr 23, 2007 at 05:10:13PM +0900, David Cournapeau wrote:
Hi,
I wanted to know what is the status of the doc format for scipy (http://projects.scipy.org/scipy/numpy/wiki/DocstringStandards) ? Is anything settled down ?
The latest document I know of is at http://projects.scipy.org/scipy/numpy/browser/trunk/numpy/doc/HOWTO_DOCUMENT... Cheers Stéfan
![](https://secure.gravatar.com/avatar/9820b5956634e5bbad7f4ed91a232822.jpg?s=120&d=mm&r=g)
Stefan van der Walt wrote:
On Mon, Apr 23, 2007 at 05:10:13PM +0900, David Cournapeau wrote:
Hi,
I wanted to know what is the status of the doc format for scipy (http://projects.scipy.org/scipy/numpy/wiki/DocstringStandards) ? Is anything settled down ?
The latest document I know of is at
http://projects.scipy.org/scipy/numpy/browser/trunk/numpy/doc/HOWTO_DOCUMENT... Do you know how to process it ? I tried epydoc beta, and it does not work on a simple example, and dies on numpy sources...
David
![](https://secure.gravatar.com/avatar/af6c39d6943bd4b0e1fde23161e7bb8c.jpg?s=120&d=mm&r=g)
On Mon, Apr 23, 2007 at 07:10:14PM +0900, David Cournapeau wrote:
Stefan van der Walt wrote:
On Mon, Apr 23, 2007 at 05:10:13PM +0900, David Cournapeau wrote:
I wanted to know what is the status of the doc format for scipy (http://projects.scipy.org/scipy/numpy/wiki/DocstringStandards) ? Is anything settled down ?
The latest document I know of is at
http://projects.scipy.org/scipy/numpy/browser/trunk/numpy/doc/HOWTO_DOCUMENT... Do you know how to process it ? I tried epydoc beta, and it does not work on a simple example, and dies on numpy sources...
AFAIK, no parser has been written for that format yet. Cheers Stéfan
![](https://secure.gravatar.com/avatar/67eadceb08f909ead3915fc9d9145a7d.jpg?s=120&d=mm&r=g)
http://projects.scipy.org/scipy/numpy/browser/trunk/numpy/doc/HOWTO_DOCUMENT... Do you know how to process it ? I tried epydoc beta, and it does not work on a simple example, and dies on numpy sources...
I updated epydoc and the patch I wrote a while ago to parse something very near the scipy template are now outdated. On the other hand, simple examples should work... Do you get a latex error or a python error ? If you get a latex inputenc error, it may be a due to using latin1 encoding instead of utf8 or whatever your encoding is (look in the header of api.tex). HTH, David
![](https://secure.gravatar.com/avatar/9820b5956634e5bbad7f4ed91a232822.jpg?s=120&d=mm&r=g)
David Huard wrote:
> > http://projects.scipy.org/scipy/numpy/browser/trunk/numpy/doc/HOWTO_DOCUMENT... > Do you know how to process it ? I tried epydoc beta, and it does not > work on a simple example, and dies on numpy sources...
I updated epydoc and the patch I wrote a while ago to parse something very near the scipy template are now outdated.
On the other hand, simple examples should work...
Do you get a latex error or a python error ?
Well, actually, I was just stupid, and forgot to set __docformat__ to reST before processing my python files... Now, I can get them processed.
If you get a latex inputenc error, it may be a due to using latin1 encoding instead of utf8 or whatever your encoding is (look in the header of api.tex).
Indeed, the package is called twice, once with utf8, once with latin1; I haven't really looked into it. Does the latex part of the docstring works ? Eg, I didn't find a way to add comment into latex and make them work with :lm:eqn, but I am not sure about the syntax (and didn't find any examples in numpy/scipy sources). Thanks, David
![](https://secure.gravatar.com/avatar/67eadceb08f909ead3915fc9d9145a7d.jpg?s=120&d=mm&r=g)
Here is a patch to the latest docutils svn implementing the math role from Jens. You can look at docutils/sandbox/jens/latex-math/test/test.txt for an example. Note that I changed the name of the role from latex-math to math, so you'll have to replace occurrences of latex-math by math. Then run rst2latex test.txt | pdflatex Cheers, David 2007/4/24, David Cournapeau <david@ar.media.kyoto-u.ac.jp>:
David Huard wrote:
> >
http://projects.scipy.org/scipy/numpy/browser/trunk/numpy/doc/HOWTO_DOCUMENT...
> Do you know how to process it ? I tried epydoc beta, and it does
not
> work on a simple example, and dies on numpy sources...
I updated epydoc and the patch I wrote a while ago to parse something very near the scipy template are now outdated.
On the other hand, simple examples should work...
Do you get a latex error or a python error ?
Well, actually, I was just stupid, and forgot to set __docformat__ to reST before processing my python files... Now, I can get them processed.
If you get a latex inputenc error, it may be a due to using latin1 encoding instead of utf8 or whatever your encoding is (look in the header of api.tex).
Indeed, the package is called twice, once with utf8, once with latin1; I haven't really looked into it.
Does the latex part of the docstring works ? Eg, I didn't find a way to add comment into latex and make them work with :lm:eqn, but I am not sure about the syntax (and didn't find any examples in numpy/scipy sources).
Thanks,
David _______________________________________________ Scipy-dev mailing list Scipy-dev@scipy.org http://projects.scipy.org/mailman/listinfo/scipy-dev
![](https://secure.gravatar.com/avatar/9820b5956634e5bbad7f4ed91a232822.jpg?s=120&d=mm&r=g)
David Huard wrote:
Here is a patch to the latest docutils svn implementing the math role from Jens.
You can look at docutils/sandbox/jens/latex-math/test/test.txt for an example. Note that I changed the name of the role from latex-math to math, so you'll have to replace occurrences of latex-math by math. Then run
rst2latex test.txt | pdflatex
Excuse my ignorance, but how do I use it in a docstring ? Does epydoc uses the docutils' rest parser ? David
![](https://secure.gravatar.com/avatar/9820b5956634e5bbad7f4ed91a232822.jpg?s=120&d=mm&r=g)
David Huard wrote:
Here is a patch to the latest docutils svn implementing the math role from Jens.
You can look at docutils/sandbox/jens/latex-math/test/test.txt for an example. Note that I changed the name of the role from latex-math to math, so you'll have to replace occurrences of latex-math by math. Then run
rst2latex test.txt | pdflatex Thanks, this is working great ! I have another questions regarding epydoc's usage. First, when I have a Examples section in my docstring, it is put before :Parameters: in the output html, even if I put the example section after in the docstring. Why is that ?
David
![](https://secure.gravatar.com/avatar/67eadceb08f909ead3915fc9d9145a7d.jpg?s=120&d=mm&r=g)
epydoc orders the elements of the docstring according to an hard-coded list. Here is a small patch to epydoc that lets you insert examples as :Example: an example here
trythis(a) [3,4,5]
There is certainly a better way to achieve this but I'm still not aware of it. HTH, David 2007/4/26, David Cournapeau <david@ar.media.kyoto-u.ac.jp>:
David Huard wrote:
Here is a patch to the latest docutils svn implementing the math role from Jens.
You can look at docutils/sandbox/jens/latex-math/test/test.txt for an example. Note that I changed the name of the role from latex-math to math, so you'll have to replace occurrences of latex-math by math. Then run
rst2latex test.txt | pdflatex Thanks, this is working great ! I have another questions regarding epydoc's usage. First, when I have a Examples section in my docstring, it is put before :Parameters: in the output html, even if I put the example section after in the docstring. Why is that ?
David _______________________________________________ Scipy-dev mailing list Scipy-dev@scipy.org http://projects.scipy.org/mailman/listinfo/scipy-dev
participants (4)
-
David Cournapeau
-
David Huard
-
Jonathan Guyer
-
Stefan van der Walt