Testing summary¶

I tried epydoc, sphinx, and doxygen. For each one I attempted to follow their quick start guide to get some quick results, so maybe the results would be different if I really studied them more. My overall favorite is epydoc, so I would suggest that we install some kind of cron job that runs it on the trunk every night and somehow links it up to redmine (maybe using the Embedded plugin)

epydoc¶

epydoc web site

Overall, I like epydoc the best. It was the easiest to use and ran quite fast. You just run one simple command like this:

epydoc --html leginon -o output_dir

where "leginon" is whatever module you want it to import and recursively generate documentation. In this way it is actually using python to import the module, so it requires that you have leginon in your python path. It seems to have the option of a more file based approach where you give it file names or directories to parse, but the simple import technique was easy enough. It took about two minutes to generate the html docs. The only down side is that it hangs at the end for some reason when I do this on leginon. It did not do that for my test on pyami, so this is something specific to leginon. Also, it generates a lot of warnings, so we may have to study that to see if we can improve something. In any case, it seems like all the html was generated properly. Here is the result:

http://bnc16/leginon-epydoc/

sphinx¶

sphinx web site

This seems to be for more than just parsing your code to generate docs. It have a lot more features for customizing your docs and linking between different pages. It makes it look like the python reference guide since that is what they use. Unlike epydoc, this one requires you to first edit a config file before running the doc generation. Unfortunately, I could not even figure out how to get it to parse the leginon package. Probably just takes more time to learn than the few minutes I am giving it. Especially when epydoc was so easy, why should I bother with it. I was able to create a nice looking title page anyway:

http://bnc16/leginon-sphinx/

doxygen¶

doxygen web site

This one also requires you to first edit a very long config file. I did my best, and I got it to work, but I am not impressed with the appearance of the result. It's just not as organized or as pretty as epydoc. Maybe I could learn how to tune it better, but why bother when epydoc was so easy. It also took a few minutes longer to compete the code parsing and doc generation. Here is the result:

http://bnc16/leginon-doxygen