# 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. @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