search

leginon-org / leginon-redmine-archive

1 stars 0 forks source link

API documentation #1248

Open leginonbot opened 8 months ago

leginonbot commented 8 months ago

Author Name: Jim Pulokas (Jim Pulokas) Original Redmine Issue: 1248, https://emg.nysbc.org/redmine/issues/1248 Original Date: 2011-03-18 Original Assignee: Christopher Irving

Figure out which document generator to use. I am testing out epydoc, sphinx and doxygen.

leginonbot commented 8 months ago

Original Redmine Comment Author Name: Jim Pulokas (Jim Pulokas) Original Date: 2011-03-18T20:30:54Z

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":http://www.redmine.org/projects/redmine/wiki/PluginEmbedded)

epydoc

"epydoc web site":http://epydoc.sourceforge.net/

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



http://bnc16/leginon-epydoc/

# sphinx

"sphinx web site":http://sphinx.pocoo.org/index.html

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":http://www.stack.nl/~dimitri/doxygen/index.html

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
leginonbot commented 8 months ago

Original Redmine Comment Author Name: Amber Herold (Amber Herold) Original Date: 2011-06-29T16:04:09Z

Hey guys, I'd like to start using one of these as soon as possible for the recon changes. Epydoc looks great for python, but it does not look like it supports PHP. I would prefer to use just one tool for all languages. I see that doxygen has a difficult setup, but I prefer it because it supports many languages.

Thoughts?

leginonbot commented 8 months ago

Original Redmine Comment Author Name: Anchi Cheng (@anchi2c) Original Date: 2011-06-30T08:51:45Z

As I will only be a user on this. I would use anything that Christopher install. I do prefer one doc api for all languages. If the main difficulty is configuration for deoxygen, and it can parse the code by itself later, at least it doesn't need to be done every time. Is the parsing format very different between the two?