Opened 3 years ago

Closed 5 weeks ago

#571 closed task (fixed)

Automatic documentation

Reported by: mmcgrath Owned by: mmcgrath
Priority: minor Milestone: Not scheduled yet
Component: Documentation Version: trunc
Keywords: Cc:

Description

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

Attachments (2)

Doxyfile (103.8 KB) - added by cyue 4 months ago.
This is the configuration file for doxygen when it is used to generate offline webpage-form documentation for ORCHIDEE.
StomateMainCallGraph.png (314.7 KB) - added by cyue 4 months ago.
This is an examples of the call graph generated by doxygen for ORCHIDEE

Download all attachments as: .zip

Change History (19)

comment:1 Changed 3 years ago by mmcgrath

  • Owner changed from somebody to mmcgrath
  • Status changed from new to accepted

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

comment:2 Changed 2 years ago by mmcgrath

  • Milestone changed from ORCHIDEE 3.0 to ORCHIDEE 4.0

After discussion with Josefine, decided to reclassify.

comment:3 Changed 2 years ago by 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.

comment:4 Changed 2 years ago by luyssaert

  • Milestone changed from ORCHIDEE 4.0 to Not scheduled yet

comment:5 Changed 7 months ago by 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

comment:6 Changed 4 months ago by 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

comment:7 Changed 4 months ago by 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

comment:8 Changed 4 months ago by 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

Changed 4 months ago by cyue

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

Changed 4 months ago by cyue

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

comment:9 Changed 4 months ago by 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.

comment:10 follow-up: Changed 4 months ago by 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.

comment:11 in reply to: ↑ 10 Changed 4 months ago by 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.

comment:12 Changed 3 months ago by 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#

comment:13 Changed 7 weeks ago by 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.

Last edited 7 weeks ago by jgipsl (previous) (diff)

comment:14 Changed 7 weeks ago by jgipsl

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

comment:15 Changed 6 weeks ago by 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.

comment:16 Changed 6 weeks ago by 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.

comment:17 Changed 5 weeks ago by luyssaert

  • Resolution set to fixed
  • Status changed from accepted to closed

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

Note: See TracTickets for help on using tickets.