search

LArbys / LArCV

Liquid Argon Computer Vision
11 stars 9 forks source link

doxygen documentation #50

Open drinkingkazu opened 7 years ago

drinkingkazu commented 7 years ago

Inheriting from other projects, larcv has good portion of code with doxygen comments. I think we should extend those comments and generate doxygen rawgit page.

0) Enable doxygen script 1) Set up automated doxygen running either per commit or periodically 2) Set up web page w/ doxygen output OR push doxygen outcome to rawgit 3) Extend doxygen comments to non-commented code

... are the to-do's.

twongjirad commented 7 years ago

maybe this is what you mean for (2), but I think github can show the doxygen pages:

http://rickfoosusa.blogspot.com/2011/10/howto-use-doxygen-with-github.html

drinkingkazu commented 7 years ago

I meant rawgit like this: https://rawgit.com/NevisUB/laropencv_doc/master/html/annotated.html

But that looks better!

drinkingkazu commented 7 years ago

OK, I read the page you suggested. First I noticed this page is dated back to 2011 which is pretty old. Second I noticed, as opposed to what is kind of "advertised" @ beginning, the process author is describing actually requires by-hand doxygen and push each time you commit actual project code.

To me at this point it looks like a method suggested before rawgit became popular. So probably rawgit is a better way to go. That said gh-pages is more generic tool and I'm sure one can customize to make it work better or more suitable. But for now I suppose we should go for rawgit. Please correct me if I'm missing something.

twongjirad commented 7 years ago

Yeah, I only spent 2 mins googling a solution for how to host the dox pages. rawgit sounds good.

drinkingkazu commented 7 years ago

sigh, doxygen output is ~14MB already, mostly png files. I am guessing auto-doxy periodically (say every hour) will make a huge .git and make it harder to clone repo? not sure the best way to go. I might just set a cron on a webserver instead...

vgenty commented 7 years ago

Right, version control is for doxy perhaps not needed so my vote it a webserver (larbys.com?). I'm not sure how well this integrates into the git-flow scheme, but selecting a tagged version in doxygen is a nice feature i've used before (particularly in the case of GEANT) to browser headers at older stages of development (in case I don't want the bleeding edge version).

drinkingkazu commented 7 years ago

@vgenty yeah so I think we can push doxygen output per release to documentation specific repository while hourly build on a web server.