Run doxygen with threads.

[bangerth]

Newer doxygen versions (since late in the 1.8.* series) can use multiple threads to read input files, and to a limited degree generate dot graphs in parallel. Since generating the documentation takes quite a long time, I thought I'd play with this. This is also useful because when generating documentation, everything is funneled into doxygen which then, for several minutes, runs as the only process on systems that today have multiple cores that are then unused.

Setting two of doxygen's parameters to zero then lets doxygen choose the number of threads based on the number of available cores. This substantially reduces the build time, even though it increases the overall CPU time -- but I think the former outweighs the latter given that this is the sequential step:

old:
-----
real    4m9.948s
user    4m3.983s
sys     0m6.577s

real    4m11.068s
user    4m4.590s
sys     0m7.003s


new:
------
real    1m27.764s
user    7m1.715s
sys     0m14.377s

real    1m30.634s
user    7m2.998s
sys     0m14.391s

(Timings for everything excluding running latex to create formulas. That is apparently broken in the doxygen version I'm testing this with, with or without using multiple threads, for reasons I still have to investigate.)

[marcfehling]

The doxygen version on the 'indent' worker is 1.8.13. Yet, it complains about unsupported tags:

warning: ignoring unsupported tag `NUM_PROC_THREADS       =' at line 80, file options.dox

I'm puzzled.

[bangerth]

The flag was only introduced in 1.8.19. So I guess I have to guard the use of the flag with a version check :-(

[bangerth]

Seems to be working now.

[tjhei]

This is awesome, great find! 👍