Use doxygen to generate subroutine call graphs and offline html-form documentation

Author: Chao Yue
Last revision: 2022/06, Chao Yue

Simple instructions on how to use doxygen to generate offline webpage-form documentation for ORCHIDEE. One of the nice features is that it will show calling graph, i.e., which subroutines a given subroutine is calling and itself in turn is called by which subroutines. The call graph is also interactive. When you click on a subroutine, you will be directed to the details of this subroutine, because the offline webpages are linked. Note we are just visiting our local files using an internet browser. As a result it's not encouraged to do this on a server because it's not necessarily straightforward to install doxygen and related software on a server or to initiate a web browser and forward its content to your own monitor or screen, with the latter especially slow when the internet connection to the server is bad.

This Howto page is created under the related discussions of ticket #571 in which it's decided that automatic documentation in coding is largely removed.

Better to do this on your local computer. The steps are:

(1) Download the most recent trunk of ORCHIDEE code.

(2) To install doxygen and the another program needed (here examples on an Ubuntu or Debian machine):

sudo apt install doxygen
sudo apt-get install graphviz

(3) Inside your ORCHIDEE code folder (.../modipsl/modeles/ORCHIDEE/),

Download the attached file (with the name of "Doxyfile", which is the doxygen configuration file) and put it into this folder.

Then run the command 'doxygen Doxyfile'

You will see three new folders being added after all commands are OK:

docbook/
latex/
html/

Then go into the html folder, there is a file named 'index.html'

Open it with firefox or any other browser, you will be able to use the 'offline' documentation and check the call graph of different subroutines by looking up routines under the "Namespaces" menu.

You can also read code from this index.html file (under the "Files" menu).

Successful experiences were reported with Doxygen version 1.8.13 on Debian 9.13 (stretch), and with Doxygen version 1.9.3 on Manjaro arch-linux.