Automatic documentation

[mmcgrath]

Does the Doxygen automatic documentation system still work with ORCHIDEE trunk?

[mmcgrath]

Jan thought that Fabienne had looked at this a while ago, so I will check in with her.

[mmcgrath]

After discussion with Josefine, decided to reclassify.

[jgipsl]

For information, note that for creation of the documentation, the script makeorchidee_fcm was used. The script then used the Makefiles(based on AA_make and AA_make.ldef) in ORCHIDEE/src_* folders. But these AA_make files in ORCHIDEE/src_* have been removed because not updated anymore and not used (see ticket #669). See ORCHIDEE_2_0 (or 2_1, or 2_2) to have the full chain for the compilation of the documentation.

[pmaugis]

If the need is confirmed and sustained by the group, I might find the time to program a new script to make the automatic documentatino

[jgipsl]

If we decided to clean the automatic documentation, we could clean a big part in the makeorchidee_fcm which is not working today. We could also clean in comment part in the code.
For example, following could be removed:

!! FLOWCHART    :
!! \latexonly 
!!     \includegraphics[scale=0.5]{diffuco_main_flowchart.png}
!! \endlatexonly
!! \n

and following could be changed

!! @tex $(gC m^{-2} year^{-1})$ @endtex

into

!! gC/m2/year
or
!! gC/m^{2}/year

[jgipsl]

It was said today during the ORCH meeting that using an automatic tool to create a caller graph could be interessting but maybe not usefull to make the full documentation. To be done:

• Chao will see if he can make a caller graphe using DOXGEN.
• Josefine will ask other groups at IPSL if they use automatic tools to create documentation

[jgipsl]

For information, NEMO, INCA or LMDZ do not use automatic documention.

LMDZ creates sometimes a call graph using gprof. The results looks like the following but it doesn't include all levels of subroutines: ​https://web.lmd.jussieu.fr/~fairhead/Labo/LMDZ_Profiles/Profile_LMDZ_rev4052_jean-zay_1mois_144x142x79_71MPI10OMP.png

See here a description how to use gprof:
​https://lmdz.lmd.jussieu.fr/Members/lfairhead/ma-foire-aux-questions

[cyue]

This is the configuration file for doxygen when it is used to generate offline webpage-form documentation for ORCHIDEE.

[cyue]

This is an examples of the call graph generated by doxygen for ORCHIDEE

[cyue]

Simple instructions on how to use doxygen to generate offline webpage-form document for ORCHIDEE. The nice feature is that it will show calling graph (see attached an example). Note that the call graph is interacitve: when you click on a subroutine, you will be directed to this subroutine, because the webpages are linked.

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

(2) To install doxygen and the another program needed (on ubuntu):
sudo apt install doxygen
sudo apt-get install graphviz

(3) Inside the ../modipsl/modeles/ORCHIDEE/ folder,

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 other browser, you will be able to use the 'offline' documentation and check the call graph of different subroutines.

You can actually also read code there.

[cyue]

Propositions regarding this ticket on weekly meeting of 21/03/2022:

• The DOC folder will be removed.
• No dedicated code cleaning is planned so far. Instead, people may choose to clean the leftover of the documentation in the code when they work on specific subroutines.

[cyue]

Replying to cyue:

Propositions regarding this ticket on weekly meeting of 21/03/2022:

• The DOC folder will be removed.
• No dedicated code cleaning is planned so far. Instead, people may choose to clean the leftover of the documentation in the code when they work on specific subroutines.

While I put these from the weekly meeting here, I prefer to keep DOC folder even if it is not actively used to generate documentation of ORCHIDEE in form of pdf, for example.

The DOC folder takes a space of 912K, out of the whole ORCHIDEE of 42M. So space should not be a big consideration.

But there are some resources in DOC folder which could be potentially useful, including the equations in latex form, the flow chart. We can warn that these might be obsolete, but some people may still find them useful. For example, to copy the equation in latex form and render it by themselves – still much easier to read and help understand the code.

[jgipsl]

According to the ORCHIDEE Monday meeting previous week, it has been decided to update the coding guidelines. Chao started and I'm now continuing. But I need to be clear of what has been decidied.

I propose to keep !! (double exclamation) in the headers to the modules and subroutines and also for the numbering of the sections. If you agree, this should be corrected in several places in the coding guidelines.

For the units, I made also a simplified proposition. See 6.5 Document units
​https://docs.google.com/document/d/1xOOWkynuqpD4JIHUscUKBuTQXzyvxK5o/edit?pli=1#

[jgipsl]

Said on todays orch meeting:

• Units will be written without latex format at a simple way as done in field_def.xml file. For exempale : (gC/m^2/s)
• We keep double !! in the header for modules and subroutines as before but without the extra caracters for oxygen (remove \n and latex equations)

Josefine will update the coding guidelines accordingly.

[jgipsl]

Coding guidelines were updated. I think this ticket can be closed.

[gmarie]

I tested the "how to" in the wiki section and I managed to produced the Doxygen documentation on my local computed with the 1.9.3 version of Doxygen.

[cyue]

Further changes are made in the Howto page: (1) it's stressed that better to do it on the local computer. (2) this ticket is cited. (3) information on the version of doxygen and linux machine distribution was added.

[luyssaert]

Changes were made to the How to page. Ticket will be closed.