doxygen oddities related to code blocks in python dox

[rmandelb]

I just pushed to master an updated version of galsim/psfcorr.py that makes use of code example blocks. However, when I did this, it also puts the paragraph of text above the code block into a (separate) code block. I cannot find anything about this online and all the little reformats I tried did not change it. So:

1. does anyone else see this when they run doxygen and look at the psfcorr package functions? (it happens in both FindAdaptiveMom and EstimateShearHSM) I wonder if it could be some bugginess in my version of doxygen, 1.8.0.

2. does anyone know how to fix this? Is it just "user failure" in how I'm using code blocks? :)

Not many of our python functions in galsim/*.py have code blocks for example code, but eventually I hope that more of the commonly-used ones will, so I would like to understand this behavior.

[rmjarvis]

Did you do anything to fix this? I looked at what doxygen produces on my system and it looks fine. Two code blocks where you specified, and the rest not in code blocks. The only minor thing I see is a line that says "Parameters ---------------" just before the automatically generated Parameters block.

[rmjarvis]

By the way, (maybe this should be a separate issue) it would be nice if we could get the doxygen output up on github automatically. Here is my first foray into looking into whether this is possible:

http://www.freakinabox.com/2011/03/04/using-doxygen-with-gh-pages-on-github/

This seems like something we could add to the Jenkins runs, perhaps?

[rmandelb]

No, I didn't do anything, I was hoping a doxygen guru would be able to say what I'm doing wrong or might be familiar with this if it's a known bug. So... it sounds like we're getting different outputs. What version doxygen do you have? I just realized that's not on the build matrix.

Getting the doxygen up automatically would be a nice thing, I agree. You could ping Joe about adding it to Jenkins.

[rmjarvis]

What version doxygen do you have? I just realized that's not on the build matrix.

1.7.4

[rmandelb]

1.7.4

Okay, so mine's a later version. And just for fun I reran it and confirmed that i still see this problem.

I don't know, if nobody else is complaining and this problem depends on the version, then perhaps it's not worth leaving this issue open.

[rmjarvis]

Maybe leave this open until we get doxygen running automatically on Jenkins. Then if that output is also screwy, then we should find a way to fix it.

@joezuntz Joe, do you think we could add doxygen to the Jenkins run? (Or are you already doing that?) I found a link where someone described how to use github's gh-pages to get doxygen output up on github. (See a few comments up.) It would be cool if we could get Jenkins to do that as part of its regular runs.

[joezuntz]

Sorry I missed this earlier. On the headline issue: I don't see the same problem in my version. Can you look at the output of running:
doc/doxypy.py galsim/psfcorr.py
is the @code block matched by an @Endcode? Or is there a superfluous @code somewhere?

Github + Jenkins + Doxygen: I'll have a look at the link and give it a go.

[joezuntz]

Oops, I seem to have messaged the user called "code" there by accident. Apologies, Mr/Ms Code. You must get this all the time.

[rmjarvis]

lol. That would be an unfortunate user name, eh?

[rmandelb]

ha!

Yes, all code blocks have matching @code and @endcode before/after when I run doxypy.

[rmandelb]

I'm closing this. Nobody else sees it and it's not showing up in the version that Jenkins is producing and putting up on GitHub. I'm happy to call it a fluke produced by some combination of my system and version of doxygen, and leave it at that.