Doxygen broken on Mac OSX after latest commits

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.

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.

Yes, it just dies after the warnings.

1 Like

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.

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

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 

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

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.

what he said - builds boilerplate.

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)

1 Like

@Stevo15025, I see what you see too.

Although, the first page is broken.

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

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

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 =

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

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

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

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?

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