[Cython] code documentation tool

[Martin Gysel]

Hi

Can anybody recommend a code documentation tool which works good with
cython.
I tried doxygen but I'm rather disappointed. I see the cython project
uses sphinx for the doc. But is sphinx the best tool to generate api
docs? Is there something which can analyze cython code and do what
doxygen does with c or java?

/martin

[David Cournapeau]

Post by Martin Gysel
Hi
Can anybody recommend a code documentation tool which works good with
cython.
I tried doxygen but I'm rather disappointed. I see the cython project
uses sphinx for the doc. But is sphinx the best tool to generate api
docs?

It is the best I know for python, at least.

Post by Martin Gysel
Is there something which can analyze cython code and do what
doxygen does with c or java?

Sphinx API doc works by introspection, so it does not matter so much
whether the underlying code is in python or C (cython is "just" a tool
to generate C in that case).

You can see a simple example here I made for audiolab:

http://www.ar.media.kyoto-u.ac.jp/members/david/softwares/audiolab/sphinx/fullapi.html

And the corresponding source file:

http://github.com/cournape/audiolab/blob/4afd4853dbb273305ab8468e860bf2e651883c20/scikits/audiolab/pysndfile/_sndfile.pyx

David

[Martin Gysel]

Post by David Cournapeau
Sphinx API doc works by introspection, so it does not matter so much
whether the underlying code is in python or C (cython is "just" a tool
to generate C in that case).
http://www.ar.media.kyoto-u.ac.jp/members/david/softwares/audiolab/sphinx/fullapi.html
http://github.com/cournape/audiolab/blob/4afd4853dbb273305ab8468e860bf2e651883c20/scikits/audiolab/pysndfile/_sndfile.pyx

I looked through you code and sphinx files, the output seems to be very
nice, but I can't reproduce such an output with my code/configuration.
AFAIK sphinx gets the info for autodoc from the docstring but how does
this work for you because my docstrings are removed in the module
(according the cython doc, that's the normal behavior). did I overlook
something in your configuration?

cheers
martin

[Lisandro Dalcin]

Post by Martin Gysel
AFAIK sphinx gets the info for autodoc from the docstring but how does
this work for you because my docstrings are removed in the module
(according the cython doc, that's the normal behavior).

What are you talking about, Martin? Cython does not removes any
docstring (with a few exceptions for some special methods). However,
perhaps you need to asks Cython to auto-generate signatures for you,
just add the commented line at the very beginning of your modules:

#cython: embedsignature=True

[Martin Gysel]

Post by Lisandro Dalcin

Post by Martin Gysel
AFAIK sphinx gets the info for autodoc from the docstring but how does
this work for you because my docstrings are removed in the module
(according the cython doc, that's the normal behavior).

What are you talking about, Martin? Cython does not removes any
docstring (with a few exceptions for some special methods). However,
perhaps you need to asks Cython to auto-generate signatures for you,
#cython: embedsignature=True

thx for the hint, now everything works as expected

/martin

[Stefan Behnel]

Post by Martin Gysel
Can anybody recommend a code documentation tool which works good with
cython.
I tried doxygen but I'm rather disappointed. I see the cython project
uses sphinx for the doc. But is sphinx the best tool to generate api
docs?

Sphinx is good in generating documentation. It's not that satisfying for
generating API docs from sources or through module introspection.

Post by Martin Gysel
Is there something which can analyze cython code and do what
doxygen does with c or java?

Nothing I know of. Epydoc can read the embedded signatures, as long as you
stick with Python 2.x syntax and avoid fancy default values. It will fail
hopelessly (reg-exps, that is) for type annotations in whatever form.

I considered fixing it several times, but I guess when I start investing
this time, I'd rather fix up Sphinx' API doc generation instead. It just
looks better.

Stefan

[Lisandro Dalcin]

Post by Stefan Behnel

Post by Martin Gysel
Can anybody recommend a code documentation tool which works good with
cython.

Sphinx is good in generating documentation. It's not that satisfying for
generating API docs from sources or through module introspection.

Indeed.

Post by Stefan Behnel

Post by Martin Gysel
Is there something which can analyze cython code and do what
doxygen does with c or java?

Nothing I know of. Epydoc can read the embedded signatures, as long as you
stick with Python 2.x syntax and avoid fancy default values. It will fail
hopelessly (reg-exps, that is) for type annotations in whatever form.

However, take a look at the script in the below (works as a cmd line
replacement for epydoc)
Of course you have to remove stuff at the very beginning and at the
end (the 'epydoc.cfg' rc file stuff) ...
Moreover, this script also monkeypatch the issue of Epydoc trying to
generate GIF files in favor of PNG, as Linux distros (Fedora, in my
case) disable that format for the famous patents problems

http://code.google.com/p/mpi4py/source/browse/trunk/conf/epydocify.py

Wait a minute... I've pushed something to Cython a long time ago
(Tools/cython-epydoc.py)... But it is likely outdated...

[Robert Bradshaw]

On Mon, Mar 30, 2009 at 4:55 AM, Stefan Behnel

Post by Stefan Behnel

Post by Martin Gysel
Can anybody recommend a code documentation tool which works good with
cython.

Sphinx is good in generating documentation. It's not that
satisfying for
generating API docs from sources or through module introspection.

Indeed.

Post by Stefan Behnel

Post by Martin Gysel
Is there something which can analyze cython code and do what
doxygen does with c or java?

Nothing I know of. Epydoc can read the embedded signatures, as long as you
stick with Python 2.x syntax and avoid fancy default values. It will fail
hopelessly (reg-exps, that is) for type annotations in whatever form.

However, take a look at the script in the below (works as a cmd line
replacement for epydoc)
Of course you have to remove stuff at the very beginning and at the
end (the 'epydoc.cfg' rc file stuff) ...
Moreover, this script also monkeypatch the issue of Epydoc trying to
generate GIF files in favor of PNG, as Linux distros (Fedora, in my
case) disable that format for the famous patents problems
http://code.google.com/p/mpi4py/source/browse/trunk/conf/epydocify.py
Wait a minute... I've pushed something to Cython a long time ago
(Tools/cython-epydoc.py)... But it is likely outdated...

We got the cython patch in for embedding epydoc signature data, right?

- Robert

[Lisandro Dalcin]

On Mon, Mar 30, 2009 at 6:50 PM, Robert Bradshaw

Post by Robert Bradshaw
We got the cython patch in for embedding epydoc signature data, right?

Not sure what patch are you talking about... The auto-generation of
signature is working from long ago, but it adds types to the func
args... but epydoc cannot parse it... so the monkeypatching I'm
talking about...

[William Stein]

Post by Lisandro Dalcin

Post by Stefan Behnel

Post by Martin Gysel
Can anybody recommend a code documentation tool which works good with
cython.

Sphinx is good in generating documentation. It's not that satisfying for
generating API docs from sources or through module introspection.

Indeed.

Post by Stefan Behnel

Post by Martin Gysel
Is there something which can analyze cython code and do what
doxygen does with c or java?

Nothing I know of. Epydoc can read the embedded signatures, as long as you
stick with Python 2.x syntax and avoid fancy default values. It will fail
hopelessly (reg-exps, that is) for type annotations in whatever form.

However, take a look at the script in the below (works as a cmd line
replacement for epydoc)
Of course you have to remove stuff at the very beginning and at the
end (the 'epydoc.cfg' rc file stuff) ...
Moreover, this script also monkeypatch the issue of Epydoc trying to
generate GIF files in favor of PNG, as Linux distros (Fedora, in my
case) disable that format for the famous patents problems

This is off topic, but for the record "all the relevant patents have
expired." This is according to both Wikipedia:
http://en.wikipedia.org/wiki/Graphics_Interchange_Format and FSF
http://www.gnu.org/philosophy/gif.html

William

Post by Lisandro Dalcin
http://code.google.com/p/mpi4py/source/browse/trunk/conf/epydocify.py
Wait a minute... I've pushed something to Cython a long time ago
(Tools/cython-epydoc.py)... But it is likely outdated...
--
Lisandro Dalcín
---------------
Centro Internacional de Métodos Computacionales en Ingeniería (CIMEC)
Instituto de Desarrollo Tecnológico para la Industria Química (INTEC)
Consejo Nacional de Investigaciones Científicas y Técnicas (CONICET)
PTLC - Güemes 3450, (3000) Santa Fe, Argentina
Tel/Fax: [phone]
_______________________________________________
Cython-dev mailing list
http://codespeak.net/mailman/listinfo/cython-dev

[Fernando Perez]

Post by Stefan Behnel

Post by Martin Gysel
Can anybody recommend a code documentation tool which works good with
cython.
I tried doxygen but I'm rather disappointed. I see the cython project
uses sphinx for the doc. But is sphinx the best tool to generate api
docs?

Sphinx is good in generating documentation. It's not that satisfying for
generating API docs from sources or through module introspection.

I'm curious: why do you say that? This doesn't seem so bad to me:

http://neuroimaging.scipy.org/site/doc/manual/html/api/index.html

e.g.

http://neuroimaging.scipy.org/site/doc/manual/html/api/generated/neuroimaging.algorithms.statistics.rft.html

In the above our math wasn't using the proper rest markup so it
doesn't render right, but if you mark it up correctly, math is fine:

http://neuroimaging.scipy.org/site/doc/manual/html/users/glm_spec.html#experimental-model

and so are code examples (which can have links to your api docs if you
want, which is not so clean if you generate your api docs with some
other tool):

http://neuroimaging.scipy.org/site/doc/manual/html/users/coordinate_map.html

as well as plots:

http://neuroimaging.scipy.org/site/doc/manual/html/devel/guidelines/sphinx_helpers.html#inserting-matplotlib-plots


In all, we're pretty happy with the sphinx-based workflow, even if
we've had to write/improve some of the support plugins ourselves.

Cheers,

f

ps - the above docs have historically had a lot of different
conventions, so I cherry-picked pages that rendered OK. The ones that
don't are typically our fault, not a problem with sphinx, and we're
updating them as we go now that we're happy with the core machinery.