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

...

...

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

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

On Apr 25, 2007, at 7:43 AM, David Cournapeau wrote:

Does epydoc uses the docutils' rest parser ?

Yes.

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