Doxygen broken on Mac OSX after latest commits

Bob_Carpenter · November 27, 2019, 7:07pm

After updating to the develop branch of stan-math, the make doxygen command now fails. It appears there was a lot of change in config in the last pull request and an update to the 1.8.13 config template. I updated to Doxygen 1.8.13 on my mac and confirmed that’s what’s running.

Are there instructions for how to get doxygen working on a Mac now? I’m still running High Sierra.

Old branches still work with my existing doxygen, but anything after the config change breaks my mac’s doxygen (and also breaks @mitzimorris’s).

Here’s the exact failure:

~/cmdstan/stan/lib/stan_math(feature/0123-complex-var)$ make doxygen
mkdir -p doc/api
doxygen doxygen/doxygen.cfg
warning: the dot tool could not be found at /usr/bin/dot
/Users/carp/cmdstan/stan/lib/stan_math/README.md:4: warning: Unexpected html tag <img> found within <a href=...> context
/Users/carp/cmdstan/stan/lib/stan_math/README.md:8: warning: unable to resolve reference to `https:' for \ref command

I don’t have dot on my path as there’s no hit for which dot.

syclik · November 27, 2019, 7:23pm

cc: @Stevo15025 @rok_cesnovar

@Bob_Carpenter, I see the same things, but they seem to be warnings. Does it fail to build for you?

@Stevo15025, let’s get rid of the warnings.

Bob_Carpenter · November 27, 2019, 7:25pm

Yes, it just dies after the warnings.

syclik · November 27, 2019, 7:27pm

Ok. That’s not ok. Do you know if it’s spitting out an error code?

> echo $?

If it’s a 0, then it’s failing silently and that’s even worse than failing with an error.

Stevo15025 · November 27, 2019, 8:06pm

The errors odd since I turned off the option to make the dot graphs, but maybe on mac it’s doing something odd. I can look into what’s goofing on this today

Bob_Carpenter · November 27, 2019, 8:09pm

It completes, but doesn’t generate any doc for the API, just the boilerplate.

~/cmdstan/stan/lib/stan_math(feature/0123-complex-var)$ make clean-all
  removing test executables
rm -f 
  removing generated test files
rm -f 
  removing doxygen
rm -f -r doc/api
  removing dependency files
  cleaning sundials targets
rm -f 
  cleaning Intel TBB targets
rm -f -rf lib/tbb

~/cmdstan/stan/lib/stan_math(feature/0123-complex-var)$ make doxygen
mkdir -p doc/api
doxygen doxygen/doxygen.cfg
warning: the dot tool could not be found at /usr/bin/dot
/Users/carp/cmdstan/stan/lib/stan_math/README.md:4: warning: Unexpected html tag <img> found within <a href=...> context
/Users/carp/cmdstan/stan/lib/stan_math/README.md:8: warning: unable to resolve reference to `https:' for \ref command

~/cmdstan/stan/lib/stan_math(feature/0123-complex-var)$ echo $?
0

~/cmdstan/stan/lib/stan_math(feature/0123-complex-var)$ ls doc/api/html/
bc_s.png		d4			db			doxygen.png		nav_g.png		resize.js		sync_on.png
bdwn.png		d5			dc			dynsections.js		nav_h.png		search			tab_a.png
closed.png		d6			dd			folderclosed.png	navtree.css		splitbar.png		tab_b.png
d0			d7			de			folderopen.png		navtree.js		standoxy.css		tab_h.png
d1			d8			df			index.html		navtreedata.js		stanlogo-main.png	tab_s.png
d2			d9			doc.png			jquery.js		navtreeindex0.js	svgpan.js		tabs.css
d3			da			doxygen.css		nav_f.png		open.png		sync_off.png		usergroup0.html

~/cmdstan/stan/lib/stan_math(feature/0123-complex-var)$ open doc/api/html/index.html

Stevo15025 · November 27, 2019, 8:26pm

interesting, so I built this locally on my mac (OS High Sierra), I got the warnings

doxygen doxygen/doxygen.cfg
warning: the dot tool could not be found at /usr/bin/dot
/Users/wvz764/github/opensource/math/stan/math/opencl/copy.hpp:218: warning: argument 'src' from the argument list of stan::math::copy_cl has multiple @param documentation sections

But also the index.html did compile and the site looks fine locally. For the 2nd warning I looked at copy.hpp and I’m not sure yet what’s causing that warning since that doc comment doesn’t have multiple definitions of @param src

I think I’ve seen the first warning before, for some reason doxygen has a hard time finding dot even if it’s installed in /usr/bin/dot. dot graph generation is turned off tho’ so I’m surprised it’s even trying to connect to dot. lemme play around with this for a minute I’m pretty sure there’s an easy answer

mitzimorris · November 27, 2019, 9:41pm

I updated my brew-verse - so now using latest doxygen - 1.8.16.
I tried using doxygen 1.8.13, but that version complained about hrefs in the README.md file.
(at this point, there are so many ~~kobalds~~ gremlins in the system, who knows?)

if you use brew as the installer for graphviz, it puts things in /usr/bin/local, not /usr/bin.
(note: macports might be installing it in /usr/bin )
changing file doxygen.cfg variable DOT_PATH to /usr/bin/local solves that problem.

however, the resulting build in doc/api isn’t finding the stan or eigen directories and/or is not finding the code. what gets built is only the stuff in markdown files.

mitzimorris · November 27, 2019, 9:42pm

what he said - builds boilerplate.

Stevo15025 · November 27, 2019, 10:51pm

Some things did get moved around, are you able to see the math namespace like here in the dropdown?

Can you post a screenshot of what your seeing? I’m not sure I understand what boilerplate is in this context (97% of the site’s stuff is boilerplate to me)

syclik · November 28, 2019, 4:29am

@Stevo15025, I see what you see too.

Although, the first page is broken.

(See the weird close tag that’s just hanging out?)

mitzimorris · November 30, 2019, 3:55pm

building from develop, upgraded to latest doxygen (1.8.16):

Kevin_Van_Horn · December 2, 2019, 7:59pm

I ran into this same issue on the developer branch. I resolved it (for stan_math) by editing two lines in doxygen/doxygen.cfg:

-HAVE_DOT = NO
+HAVE_DOT = YES

-DOT_PATH = /usr/bin/dot
+DOT_PATH =

Stevo15025 · December 2, 2019, 8:56pm

Yes my apologies, I think the issue here is the interaction of the two lines above. Since HAVE_DOT is false it should not care about dot, but I think because I set the dot_path it then thinks at some other stage we want dot available

Stevo15025 · December 2, 2019, 8:57pm

So I think a fix of just commenting out dot path should work i.e.

mitzimorris · December 3, 2019, 11:49pm

nope, Doxygen is not generating modules/namespaces/files tabs.

mitzimorris · December 4, 2019, 12:44am

I think the problem is with the exclude paths.
did a diff current doxygen.cfg and the version that was tagged release 2.20.0
(https://github.com/stan-dev/math/commit/23ccc2731dae9bd977c84b2fe4441f98bb908020#diff-f30854e5d588642eb89b1d68ed85992e)
and changed exclude paths to match that and that worked -
here’s the result of a side-by-side diff of old and new files

831:EXCLUDE                = */test/* \								   |	EXCLUDE                = test/*
851:EXCLUDE_PATTERNS       = */lib/*								   |	EXCLUDE_PATTERNS       =
862:EXCLUDE_SYMBOLS        = std::* \								   |	EXCLUDE_SYMBOLS        =

also getting the following error:

/Users/mitzi/github/stan-dev/cmdstan/stan/lib/stan_math/stan/math/opencl/copy.hpp:184: warning: argument 'src' from the argument list of stan::math::copy_cl has multiple @param documentation sections

@Stevo15025 - any thoughts?

Stevo15025 · December 4, 2019, 6:48pm

Apologies I’ve been running around with work and holiday stuff I’ll take a look / fix this over the weekend

I’m 90% sure I know what’s going on