source: trunk/SRC/Documentation/xmldoc/doidldoc.sh @ 437

Last change on this file since 437 was 437, checked in by pinsard, 14 years ago

test (not yet ok) with idldoc 3.2 using rst headers
  • Property svn:executable set to *
  • Property svn:keyword set to Id
  • Property svn:keywords set to Id
File size: 17.8 KB
Line 
1#! /bin/sh -x
2#+
3#
4# NAME
5# ====
6#
7# idldoc.sh - build idldoc documentations
8#
9# SYNOPSYS
10# ========
11#
12# ``doidldoc.sh -i indir -t title -o outdir -idl_dir idl_dir -idldoc_version idldoc_version -idldoc_dir idldoc_dir -e element -r refhtlm``
13#
14# DESCRIPTION
15# ===========
16#
17# Produce HTML files from IDL sources using idldoc.
18#
19# -i directory input
20# -t title
21# -o directory output
22# -idl_dir idl_dir
23# -idldoc_version idldoc_version
24# -idldoc_dir idldoc_dir
25# -e element
26# -r refhtml
27#
28# Two passes : first *classic* idldoc then some home made transformation
29# to avoid for example version of idldoc on each HTML files.
30#
31# The first pass produce files in /tmp/idldoc_output_${$}/ directory.
32#
33# At the end the result is in ``outdir``.
34#
35# By default, embedded ``idldoc`` 2.0 in SAXO is used.
36#
37# You can specified an other ``idldoc`` implentation by specify directory and
38# version using *idldoc_dir* and *idldoc_version*.
39#
40# Be warned that assitant help is only available with ``idldoc 2.0``.
41#
42# Must be run two times to resolve internal links.
43#
44# CAUTIONS
45# ========
46#
47# SAXO_DIR must be set. The value should be the directory where
48# SAXO is available.
49#
50# for example, if you work at LOCEAN and work with default SAXO,
51# SAXO_DIR=/usr/home/smasson/SAXO_DIR/.
52#
53# For working in progress, you should checkout SAXO on a personnal
54# directory and set SAXO_DIR to the working space.
55#
56# example for me : SAXO_DIR=/usr/lodyc/incas/fplod/SAXO_DIR_ws/
57#
58# EXAMPLES
59# ========
60#
61# Results can be seen be opening a browser on /tmp/idldoc_html_output/index.html
62#
63# To produce SAXO HTML outputs :
64# ::
65#
66# $ cd ${SAXO_DIR}/SRC/Documentation/xmldoc/
67# $ ${SAXO_DIR}/SRC/Documentation/xmldoc/doidldoc.sh -i ../.. -t "SAXO Documentation" -o ../idldoc_html_output/ -idl_dir /usr/local_linux/idl/idl_6.4/idl/ -e pro -r ../idldoc_html_output/ -e proidl -r /usr/local_linux/idl/idl_6.4/idl/help/online_help
68#
69#
70# To produce GEOMAG HTML outputs :
71# ::
72#
73# $ cd /usr/home/fplod/incas/geomag/geomag_ws/
74# $ ${SAXO_DIR}/SRC/Documentation/xmldoc/doidldoc.sh -i . -t "GEOMAG Documentation" -o /usr/work/incas/${LOGNAME}/geomag/idldoc_html_output/ -idl_dir /usr/local_linux/idl/idl_6.4/idl/ -e pro -r ../idldoc_html_output/ -e proidl -r /usr/local_linux/idl/idl_6.4/idl/help/online_help -e progeomag -r /usr/work/incas/${LOGNAME}/idldoc_html_output/
75
76#
77# To produce VARAMMA HTML outputs :
78# ::
79#
80# $ cd /usr/home/fplod/incas/varamma/varamma_ws/
81# $ ${SAXO_DIR}/SRC/Documentation/xmldoc/doidldoc.sh -i . -t "VARAMMA Documentation" \
82#   -o /tmp/idldoc_html_output/ -idl_dir /usr/local_linux/idl/idl_6.4/idl/ \
83#   -idldoc_version 3.2 -idldoc_dir /usr/home/incas/francoise/idldoc-3.2_aedon.locean-ipsl.upmc.fr///idldoc-3.2/ \
84#   -e pro -r ../idldoc_html_output/ -e proidl -r /usr/local_linux/idl/idl_6.4/idl/help/online_help
85#
86# To produce POST_IT HTML outputs :
87# ::
88#
89# $ cd /usr/lodyc/incas/fplod/post_it_ws/
90# $ ${SAXO_DIR}/SRC/Documentation/xmldoc/doidldoc.sh -i . -t "POST_IT/Documentation" -o /usr/work/incas/${LOGNAME}/idldoc_html_output/ -idl_dir /usr/local_linux/idl/idl_6.4/idl/ -e pro -r ${SAXO_DIR}/SRC/Documentation/idldoc_html_output/ -e proidl -r /usr/local_linux/idl/idl_6.4/idl/help/online_help -e propost_it -r /usr/work/incas/${LOGNAME}/idldoc_html_output/
91#
92# TODO
93# ====
94#
95# ++ choix de la version de idldoc et consequences sur assistant
96#
97# ++ choix de la version de IDL et consequences sur assistant et lien sur
98# doc idl
99#
100# idldoc 3.2 (beware of sphinx compatibility)
101#
102# add checking of consistency between numbers of -e and -r parameters
103#
104# SEE ALSO
105# ========
106#
107# idldoc++ lien
108#
109# pro2href.sh
110#
111# EVOLUTIONS
112# ==========
113#
114# $Id$
115#
116# - fplod 20100701T144720Z aedon.locean-ipsl.upmc.fr (Darwin)
117#
118#   * test with idldoc 3.2 (no more 3.1.1) on VARAMMA project. not yet ok
119#
120# - fplod 20100125T105849Z aedon.locean-ipsl.upmc.fr (Darwin)
121#
122#   * add -e and -r parameters to replace hardcoded element and reference
123#     of links
124#
125# - fplod 20091112T101526Z zeus.locean-ipsl.upmc.fr (Linux)
126#
127#   * replace mv by cp -r because mv may no works accross filesystems
128#   * add chek on outdir
129#
130# - fplod 20091112T084225Z aedon.locean-ipsl.upmc.fr (Darwin)
131#
132#   * bug fix if indir is set to '.'
133#   * idl_dir in parameter
134#   * path of local commands
135#
136# - fplod 20091110T151839Z aedon.locean-ipsl.upmc.fr (Darwin)
137#
138#   * add CAUTIONS about SAXO_DIR environment variable
139#     and usage in EXAMPLES
140#
141# - ++
142#
143# * add idldoc_version and idldoc_dir parameters
144# idldoc version is usefull because parameters of ``idldoc``
145# have been modified (see ``CHARSET`` in 3.1.1.).
146#
147# ``idldoc`` release can not be guessed
148#
149# - fplod 2008-08-11T12:57:48Z aedon.locean-ipsl.upmc.fr (Darwin)
150#
151# * comments in this file in ReST format
152# * add ``-i``, ``-t`` and ``-o`` parameters
153#
154# - fplod 2008-06-20T13:07:59Z aedon.locean-ipsl.upmc.fr (Darwin)
155#
156# * evaluation version 3.1.1
157#
158# we are not yet still ready to migrate to rst format because of lack of
159# assistant transformation independant of IDLdoc release (at least
160# between 2. and 3.)
161#
162# - fplod 2008-01-10T08:13:41Z aedon.locean-ipsl.upmc.fr (Darwin)
163#
164# * version http://cookbook.idldev.com/idldoc-3.0rc2.zip
165#
166# - fplod 2008-01-03T09:59:18Z aedon.locean-ipsl.upmc.fr (Darwin)
167#
168# * version http://cookbook.idldev.com/idldoc-3.0rc1.zip
169#
170# - fplod 2007-12-12T09:47:04Z aedon.locean-ipsl.upmc.fr (Darwin)
171#
172# * version http://michaelgalloy.com/wp-content/uploads/2007/12/idldoc-3.0b4.zip
173#
174# - fplod 2007-12-11T09:14:04Z aedon.locean-ipsl.upmc.fr (Darwin)
175#
176# * version http://michaelgalloy.com/wp-content/uploads/2007/12/idldoc-3.0b4-src.zip
177# * ++ pb path
178# * beginning of docbook templates writing (from html 3.0b3 tt files)
179#
180# - fplod 2007-12-10T09:28:11Z aedon.locean-ipsl.upmc.fr (Darwin)
181#
182# * test with gdl : pas possible car compatibility < 6.1
183#
184# - fplod 2007-12-04T09:21:18Z aedon.locean-ipsl.upmc.fr (Darwin)
185#
186# * version http://michaelgalloy.com/wp-content/uploads/2007/12/idldoc-3.0b3.zip
187# * pb parser if ; after ;-
188# * ++ plus de param et keyword dans l'index
189# * ++ pas w3c tilte au lieu de title, pas de charset, pas de alt, pas de summary
190# * ++ css pas ok
191# * ++ plus de @restrictions
192#
193# - fplod 2007-12-04T09:10:55Z aedon.locean-ipsl.upmc.fr (Darwin)
194#
195# * externalisation of idldoc issues from savesaxo.sh
196# * previous release of idldoc was 2.0
197# * this tool can be checked by creating doc from Michael Galloy librayry
198# available on http://www.michaelgalloy.com/lib-docs/
199# * version http://michaelgalloy.com/wp-content/uploads/2007/11/idldoc-3.0b1.zip
200# * pas ok ne reconnait pas les @param, @keyword
201#-
202#
203system=$(uname)
204case "${system}" in
205   AIX|IRIX64)
206      echo " www : no specific posix checking"
207   ;;
208   *)
209      set -o posix
210   ;;
211esac
212#
213command=$(basename ${0})
214log_date=$(date -u +"%Y%m%dT%H%M%SZ")
215#
216usage=" Usage : ${command} -i indir -t title -o outdir [-idldoc_dir idldoc_dir -idldoc_version idldoc_version]"
217#
218# default ++ pas encore en parametre
219assistant=0
220#assistant=1
221transform=1
222command_dir=$(dirname ${0})
223idldoc_dir="${command_dir}/../idldoc/"
224idldoc_version="2.0"
225unset command_dir
226# default IDL command and directory
227#idl_dir=/usr/local_linux/idl/idl64/  # overriding idl_dir for test ++
228#idldoc_dir="/usr/home/fplod/src/idldoc-3.1.1/" # overriding idldoc_dir for test ++
229#
230ielement=1
231#
232minargcount=6
233if [ ${#} -lt ${minargcount} ]
234then
235   echo "eee : not enought arguments"
236   echo "${usage}"
237   exit 1
238fi
239#
240set +u
241while [ ! -z "${1}" ]
242do
243   case ${1} in
244      -i)
245         indir=${2}
246         shift
247         case ${indir} in
248            .)
249               indir=$(pwd)
250            ;;
251         esac
252      ;;
253      -t)
254         title=${2}
255         shift
256      ;;
257      -o)
258         outdir=${2}
259         shift
260      ;;
261      -idldoc_dir)
262         idldoc_dir=${2}
263         shift
264      ;;
265      -idldoc_version)
266         idldoc_version=${2}
267         shift
268      ;;
269      -idl_dir)
270         idl_dir=${2}
271         shift
272      ;;
273      -e)
274         element[${ielement}]=${2}
275         shift
276      ;;
277      -r)
278         refhtml[${ielement}]=${2}
279         shift
280         ielement=$(( ${ielement} + 1))
281      ;;
282      -h)
283         echo "${usage}"
284         exit 0
285      ;;
286      *)
287         # other choice
288         echo "${usage}"
289         exit 1
290      ;;
291   esac
292   # next flag
293   shift
294done
295#
296set -u
297#
298# check for outir
299if [ ! -d ${outdir} ]
300then
301   echo "eee : outdir (${outdir}) not found"
302   exit 1
303fi
304# check for permission access on outdir
305if [ ! -x ${outdir} ]
306then
307   echo " eee : ${outdir} not reachable"
308   exit 1
309fi
310#
311# check for write permission on outdir
312if [ ! -w ${outdir} ]
313then
314   echo " eee : ${outdir} not writable"
315   exit 1
316fi
317#
318# ++ test si IDL (car GDL inutilisable)
319application=${idl_dir}/bin/idl
320#
321# build a IDL file to launch idldoc
322outputtmp=/tmp/idldoc_output${$}/
323idldoc_log="/tmp/idldochtml_${$}.log"
324pro="/tmp/idldochtml_${$}.pro"
325#
326cd ${idldoc_dir}
327case ${idldoc_version} in
328   3.2)
329      cat << EOF > ${pro}
330!path = expand_path('+' + '${idldoc_dir}')
331idldoc,root="${indir}",title="${title}", $
332CHARSET="ISO-8859-15", $
333LOG_FILE="${idldoc_log}", $
334output="${outputtmp}", $
335overview="../../overview", /statistics
336exit
337EOF
338   ;;
339   2.0)
340      cat << EOF > ${pro}
341!path = expand_path('+' + '${idldoc_dir}')
342idldoc,root="${indir}",title="${title}", $
343LOG_FILE="${idldoc_log}", $
344output="${outputtmp}", $
345overview="../../overview", /statistics, /preformat
346exit
347EOF
348   ;;
349   *)
350      echo "eee : idldoc version not implemented ${idldoc_version}"
351      exit 1
352   ;;
353esac
354#
355# launch IDL with the file built above
356export IDL_STARTUP=${pro}
357${application}
358rm ${pro}
359#
360if [ ${transform} -eq 1 ]
361then
362   # In order to do not have to many revision in svn, we modify some
363   # lines produced by idldoc :
364   # - add Source link in each html file corresponding to a .pro file
365   # example :
366   # <td>Source</td>
367   # will be replaced by
368   # <td><a href="../../Calendar/caldat.pro" title="Source code of a file">Source</a></td>
369   #
370   # - remove version, date and time of idldoc production
371   # ++ je ne sais pas dire en sed la ligne suivant l'occurence de Modification date
372   #
373   # count of directory levels in output
374   # this count will be use to format relative path later
375   nblev1=$(echo ${outputtmp} | sed -e "s@/\$@@" |awk -F "/" '{print NF}')
376   #
377   list_html_pro=$(find ${outputtmp} -name "*.html" -exec grep -l "<title>.*\.pro" {} \;)
378   for file_html in ${list_html_pro}
379   do
380      # build the .pro file name
381      bfile=$(basename ${file_html} .html)
382      # retrieve the path of html file relative to output.
383      # This path will be used in "Source" link.
384      nblev2=$(dirname ${file_html} | sed -e "s@/\$@@" | awk -F "/" '{print NF}')
385      difflev=$((${nblev2} - ${nblev1}))
386      if [ ${difflev} -ge 2 ]
387      then
388         ilev=1
389         reloutput_html=".."
390         while [ ${ilev} -le ${difflev} ]
391         do
392            reloutput_html="${reloutput_html}/.."
393            ilev=$(( ${ilev} + 1 ))
394         done
395         relpath_html=$(dirname ${file_html} | \
396            sed \
397               -e "s@${outputtmp}@${reloutput_html}@" \
398               -e "s@\$@/@")
399         # echo "relpath ${relpath_html})"
400      else
401         relpath_html="./"
402      fi
403      # echo "relpath ${relpath_html}/${bfile}"
404      sed \
405         -e "s@<td >Source<\/td>@<td><a href=\"${relpath_html}/${bfile}.pro\" title=\"Source code of a file\">Source<\/a><\/td>@" \
406         ${file_html} > ${file_html}_modify
407      mv ${file_html}_modify ${file_html}
408   done
409   list_html=$(find ${outputtmp} -name "*.html")
410   for file_html in ${list_html}
411   do
412      sed \
413         -e "s/\(Generated by IDLdoc\)\( .* on .*\)\( -->\)/\1\3/" \
414         -e "s/\(Produced by IDLdoc\)\( .* on .*\)\(<\/div>\)/\1\3/" \
415         -e "/<h2>Produced on/d" \
416         -e "/Modifcation:/d" \
417         -e "/<td>... ... .* ..:..:.. ....<\/td>/d" \
418         -e 's@<div class="value">@<div class="preformat">@' \
419         -e 's/div\#file_comments {/div\#file_comments { white-space: pre;/' \
420         -e 's@^ <fixe>@<pre>@' \
421         -e 's@^ </fixe>@</pre>@' \
422         -e 's@xhtml-transitional@xhtml1-transitional@' \
423         ${file_html} > ${file_html}_modify
424      mv ${file_html}_modify ${file_html}
425   done
426   # suppress ".html" in idldoc-index*.html in lines like
427   # a parameter from the routine ./ReadWrite/idl-NetCDF/ncdf_read.html
428   list_html=$(find ${outputtmp} -name "idldoc-index*.html")
429   for file_html in ${list_html}
430   do
431      sed \
432         -e "s/\(a parameter from the routine \)\(.*\)\(.html\)/\1\2/" \
433         ${file_html} > ${file_html}_modify
434      mv ${file_html}_modify ${file_html}
435   done
436   nelement=${#element[@]}
437   ielement=1
438   while [ ${ielement} -le ${nelement} ]
439   do
440      # replace <element>ginette</element> by a sequence like
441      # <a href="./ginette.html">ginette</a>
442      ${SAXO_DIR}/SRC/Documentation/xmldoc/pro2href.sh -i ${outputtmp} \
443         -r ${refhtml[${ielement}]} \
444         -e ${element[${ielement}]}
445      status=${?}
446      if [ ${status} -ne 0 ]
447      then
448         echo "eee : pb during pro2href.sh for ${element}...</${element}>"
449         exit 1
450      fi
451      ielement=$(( ${ielement} + 1))
452   done
453   # end of transform = 1
454fi
455#
456#
457if [ ${assistant} -eq 1 ]
458then
459   # build a IDL file to launch idldoc
460   idldoc_log="/tmp/idldocassistant_${$}.log"
461   pro="/tmp/idldocassistant_${$}.pro"
462   case ${idldoc_version} in
463      3.2)
464         echo "iii : assistant is not feasable with idldoc > 2.0"
465      ;;
466      2.0)
467         cat << EOF > ${pro}
468!path = expand_path('+' + '${idldoc_dir}')
469idldoc,root="${indir}",title="${title}", $
470LOG_FILE="${idldoc_log}", $
471output="${outputtmp}", overview='../../overview', /statistics, /embed, /assistant
472exit
473EOF
474      ;;
475      *)
476         echo "eee : idldoc version not implemented ${idldoc_version}"
477         exit 1
478      ;;
479   esac
480   # launch IDL with the file built above
481   IDL_STARTUP=${pro};${idl_dir}/bin/idl
482   /bin/rm ${pro}
483   # In order to do not have to many revision in svn, we modify some
484   # lines produced by idldoc :
485   # examples :
486   # <!-- Generated by IDLdoc 2.0 on Wed Jun 7 10:25:28 2006 -->
487   # will be replaced by
488   # <!-- Generated by IDLdoc 2.0 -->
489   # <p><font color="gray" size="-3">&nbsp;&nbsp;Produced by IDLdoc 2.0 on Wed Sep 13 16:32:10 2006.</font></p>
490   # will be replaced by
491   # <p><font color="gray" size="-3">&nbsp;&nbsp;Produced by IDLdoc 2.0</font></p>
492   # <h2>Produced on Wed Jun 7 10:23:13 2006</h2>
493   # will be delete
494   # other lines will be deleted because the time is the time of checkout not
495   # the time of revision.
496   # the sequence of lines
497   #<dl>
498   # <dt>Last modification:</dt>
499   # <dd>Fri Jun 2 11:46:24 2006</dd>
500   # </dl>
501   # should also be removed ++ je ne sais pas dire en sed la ligne
502   # suivant l'occurence de Last modification
503   # replace *_param_* in href attributes because anchors are badly written
504   # with _keyword_
505   #++ -e 's@\(href="#_.*\)\(_param_\)\(.*"\)@\1_keyword_\3@g' \ # ++ pb global
506   # ONLINE_HELP, book="../idldoc_assistant_output/idldoc-lib.adp", /full_path # won't work
507   # encaspulate example content in <pre> </pre> in idldoc assistant outputs
508   # Examples section is supposed to start with <h3>Examples</h3>
509   # and end is before <h3>Version history</h3>
510   list_html=$(find ${outputtmp} -name "*.html")
511   for file_html in ${list_html}
512   do
513      sed \
514         -e "s/\(Generated by IDLdoc 2.0\)\( on .*\)\( -->\)/\1\3/" \
515         -e "s/\(Produced by IDLdoc 2.0\)\( on .*\)\(\.<\/font>\)/\1\3/" \
516         -e "/<h2>Produced on/d" \
517         -e "/Last modification:/d" \
518         -e "/<dd>... ... .* ..:..:.. ....<\/dd>/d" \
519         -e '/href/s@_param_@_keyword_@g' \
520         -e 's@<div class="value">@<div class="preformat">@' \
521         -e 's/div\#file_comments {/div\#file_comments { white-space: pre;/' \
522         -e 's@^ <fixe>@<pre>@' \
523         -e 's@^ </fixe>@</pre>@' \
524         -e "s@<h3>Examples</h3>@<h3>Examples</h3><pre>@" \
525         -e "s@<h3>Version history</h3>@</pre><h3>Version history</h3>@" \
526         ${file_html} > ${file_html}_modify
527      mv ${file_html}_modify ${file_html}
528   done
529   #
530   # replace <pro>ginette</pro> by a sequence like
531   # <a href="./ginette.html">ginette</a>
532   ${SAXO_DIR}/SRC/Documentation/xmldoc/pro2href.sh -i ${outputtmp} -r ${outputtmp} -e pro
533   status=${?}
534   if [ ${status} -ne 0 ]
535   then
536      echo "eee : pb during pro2href.sh for <pro>...</pro>"
537      exit 1
538   fi
539   # replace <proidl>ginette</proidl> by a sequence like
540   # <a href="./ginette.html">ginette</a>
541   ${SAXO_DIR}/SRC/Documentation/xmldoc/pro2href.sh -i ${outputtmp} -r ${idl_dir}/help/online_help -e proidl
542   status=${?}
543   if [ ${status} -ne 0 ]
544   then
545      echo "eee : pb during pro2href.sh for <proidl>...</proidl>"
546      exit 1
547   fi
548   # add the directory-overview.html from dir-files.html in idldoc_html_output
549   list_html=$(find ../idldoc_html_output -name dir-files.html)
550   for file_html in ${list_html}
551   do
552      fout=../idldoc_assistant_output/${file_html#../idldoc_html_output/*}
553      fout=${fout%/*}/directory-overview.html
554      cp ${file_html} ${fout}
555   done
556   # copy listings.css (needed by directory-overview.html files)
557   cp ../idldoc/resource/listings.css ${outputtmp}
558   # add an id in idldoc-lib.adp
559   cat << EOF > /tmp/adp_modification
560<!-- \$Id\$ -->
561EOF
562   sed -e "/<\/profile>/r /tmp/adp_modification" \
563      ../idldoc_assistant_output/idldoc-lib.adp > \
564      ../idldoc_assistant_output/idldoc-lib.adp_${$}
565   mv ../idldoc_assistant_output/idldoc-lib.adp_${$} \
566   ../idldoc_assistant_output/idldoc-lib.adp
567   rm /tmp/adp_modification
568   # check that the number of existing html files for each .pro file is 2!
569   for i in $( find ../.. -name "*.pro" )
570   do
571      nhtml=$( find ../.. -name $( basename ${i} .pro ).html | wc -l )
572      if [ ${nhtml} -ne 2 ]
573      then
574         echo "ERROR there is no 2 $( basename ${i} .pro ).html files"
575         find ../.. -name $( basename ${i} .pro ).html
576         echo
577      fi
578   done
579   #
580fi
581# copy of temporary outputs on final directory
582cp -r ${outputtmp}/* ${outdir}
583echo "iii : look at ${outdir}/index.html"
584echo "iii : you can see idldoc log file in ${idldoc_log}"
585echo "iii : and look ${outdir}/idldoc-warnings.html#undoc"
586#
587# end
588exit 0
Note: See TracBrowser for help on using the repository browser.