Changes between Version 6 and Version 7 of Documentation/ORCHIDEE_DOC


Ignore:
Timestamp:
09/10/11 00:03:42 (10 years ago)
Author:
mmaipsl
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Documentation/ORCHIDEE_DOC

    v6 v7  
    2121It was decided to continue using Doxygen as the user community seems the largest (of the three tools) and the most active. In addition, new releases of Doxygen are made available regularly and the software currently has an extensive functionality. 
    2222 
     23Version 1.6.2 of Doxygen has been compiled on obelix2 here : 
     24{{{ 
     25/home/users/mmancip/PROG/doxygen-1.6.2 
     26}}} 
     27and installed in this directory : 
     28{{{ 
     29/home/users/mmancip/PROG/bin 
     30}}} 
     31You can add this tool to your own environment (here in .login file for tcsh shell) : 
     32{{{ 
     33setenv PATH /home/users/mmancip/PROG/bin:$PATH 
     34if ! ($?LD_LIBRARY_PATH) then 
     35     setenv LD_LIBRARY_PATH /home/users/mmancip/PROG/lib 
     36else 
     37     setenv LD_LIBRARY_PATH /home/users/mmancip/PROG/lib:${LD_LIBRARY_PATH} 
     38endif 
     39}}} 
     40A version 2.28.0 of graphviz set of tools has been installed in the same path. It 
     41contains last version of dot scheme builder. 
     42 
    2343== Implementation (9/2011) == 
    24 Martial coded a script that extents the functionality of Doxygen. The script allows to tag blocks of code. These blocks will end up in the documentation. This functionality was thought to be essential as it is the only way to make sure that the most recent changes to the code end-up in the documentation.[[BR]] 
    25 An Open Office plugin (writer2latex) is available to covert all type of Open Office files to Latex. Hence, existing documents can be easily transformed.[[BR]]  
     44Martial coded a script that extents the functionality of Doxygen. The script allows 
     45to tag blocks of code (@codeinc). These blocks will end up in the documentation.  
     46This functionality was thought to be essential as it is the only way to make sure 
     47that the most recent changes to the code end-up in the documentation.[[BR]]  
     48 
     49An Open Office plugin ([http://writer2latex.sourceforge.net/index.html writer2latex]) 
     50is available to convert all type of Open Office files to Latex.  
     51Hence, existing documents can be easily transformed. 
    2652 
    2753== Demonstration (9/2011) == 
    28 Fabienne will use existing and new functionalities of Doxygen to merge existing documentation with the phenology module. This will be a first example where attention will be paid to the content and appearance of the documentation. An initial set of rules has been defined but this set will most likely change following the experiences of Fabienne.[[BR]] 
    29  1. Document the smallest possible units i.e. a line of code or a couple of lines. This approach ensures that following an initial effort it is a lot easier to keep the documentation up to date as there is a clear relationship between the documentation and the code. 
    30  1. Have a scientific description at the start of the code. Avoid lengthy blocks of text because this is hard to maintain and will most likely get outdated pretty fast. It can also hamper readability of the code. 
     54Fabienne will use existing and new functionalities of Doxygen to merge existing 
     55documentation with the phenology module. This will be a first example where attention 
     56will be paid to the content and appearance of the documentation. An initial set of 
     57rules has been defined but this set will most likely change following the experiences 
     58of Fabienne.[[BR]]  
     59 1. Document the smallest possible units i.e. a line of code or a couple of lines. 
     60    This approach ensures that following an initial effort it is a lot easier to keep 
     61    the documentation up to date as there is a clear relationship between the 
     62    documentation and the code.  
     63 1. Have a scientific description at the start of the code. Avoid lengthy blocks of 
     64    text because this is hard to maintain and will most likely get outdated pretty fast. 
     65    It can also hamper readability of the code.  
    3166 1. Give full references of the scientific literature used in support of the code. 
    3267 1. Add flow charts to explain the structure of the (nested) if-then-else. 
    33  1. Each variable/parameter has a standardized description containing the following fields: Variable name, Local/Global, Dimensions, units. 
     68 1. Each variable/parameter has a standardized description containing the following 
     69    fields: Variable name, !Local/Global, Dimensions, units.  
     70 
     71You can find an example of this demonstration on obelix2 in  
     72{{{ 
     73/home/users/mmancip/PROG/ORCHIDEE_DOC_1_9_5_2/modeles/ORCHIDEE/docs 
     74}}} 
     75In latex subdirectory, you can find the refman.pdf file to be read with kpdf or 
     76acrobat. 
     77In html subdirectory, you will find the index.html to be oppened with your browser. 
     78 
     79You can get modipsl, ORCHIDEE TOOLS as discribed in SubVersion wiki page and get 
     80Martial version in modipsl/util directory with : 
     81{{{ 
     82where_is_TOOLS/recup_my_ORCHIDEE my_svn_login perso/martial.mancip my_mail@lsce.ipsl.fr 
     83}}} 
     84and then go to  
     85{{{ 
     86cd ../modeles/ORCHIDEE 
     87}}} 
     88and simply execute  
     89{{{ 
     90./makeorchidee_fcm -doc 
     91}}} 
     92to get your own version of the martial trunk documentation. 
    3493 
    3594== Open questions ==