I’m working at getting documentation generation going here for our python codebase. I’ve worked at a place where Sphinx was used, and it’s also been suggested by a few people.
We already use Doxygen for some (non-python) areas here, and I was asked to look into whether or not it would be practical to use Doxygen for our python. Does anyone have any experience with Doxygen, or, even better, comparative experience with both Doxygen and Sphinx?
I used to work at EAC and wrote a document specifically outlining how to get EA code using Doxygen. I’m sure if you check around the Techworks home page, you’ll find it.
It’s possible, I’ve used Doxygen before to document Python successfully. There are however a few things that make it a little bit nasty. I would suggest Epydoc since it’s probably the easiest to configure and works well with doc string documentation.
Sphinx here. After working with documentation systems a bit I think you’d be much better off supporting different systems for different languages especially if those different languages rarely intersect (for example, there’s a compelling reason to have CPython extension modules and python code using the same system, but very little to have your game C++ and tools python code in the same system).
Read up on using python with doxygen but I’d highly recommend Sphinx (or epydoc if ease of configuration is the most important thing).
+1 to sphinx, and if your IDE supports Sphinx style docstrings, done deal.
not being able to use docstrings for eclipse tooltip help is a major gripe I had with doxygen from the first 10 minutes of research.
We switched to Epydoc early on, mainly because of it’s easy configuration, easy doc updating and integration in PyCharm.
[QUOTE=h6x6n;13445]not being able to use docstrings for eclipse tooltip help is a major gripe I had with doxygen from the first 10 minutes of research.[/QUOTE]
I’m not sure what you are referring to. I’m using Eclipse for all my code and documenting using Doxygen and the pydoxy filter. It’s so seemless, easy and what’s more - the docs look really slick. There’s autocompletion and internal access to the docs in Eclipse for me.
The great thing about Doxygen is, obviously, it can document C++ plugins and I’ve got it working with mel. I wrote a webapp with RubyOnRails and Ajax that scrapes all the facility code, runs Doxygen on it all, sticks it in a database and provides searchable access to it all. This goes a long way to solving the perennial issue of people not being able/willing to add documentation to their code.
I haven’t mocked anything up, but looking at what was being said about doxygen all seemed to point to it not using the pythonic doc strings, and instead relying on inline comments. at that point I was thinking the tooltip pulls the help() output for some reason, not sure why I thought that. regardless, I’m hesitant to use anything that would not use the pythonic doc strings. if you’re saying that doxygen works nicely with doc strings, I’ll look further into that.
-t
You obviously get more extensive documentation if you include Doxygen’s commands in the comment block. But even without them, Doxygen generates very useable results - but you really should use the pydoxy filter.
http://i31www.ira.uka.de/~baas/pydoxy/
It also depends what kind of code you’re trying to document. If it’s just Python, then possibly one of the other options that just documents Python might be good enough. If you have multiple languages you need to document and want to provide consistency, then I think Doxygen is a great choice.
Found this via google while searching for how to use doxygen with Python, and I was wondering what your research led you to, h6x6n?
Having given Sphinx a go, I’m also looking into using doxygen, mainly because I believe the Qt and Maya API docs are generated with it and since I am familiar with it I figured it may be beneficial to make use of the style myself.
I find the Qt docs very comfortable and fast to find what I am looking as opposed to Sphinx-generated docs like the Python docs. Mainly due to the formatting and layout.