On Mon, Mar 30, 2009 at 12:55 AM, Stefan Behnel <[email protected]> wrote: > > Martin Gysel wrote: >> 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. _______________________________________________ Cython-dev mailing list [email protected] http://codespeak.net/mailman/listinfo/cython-dev
