scripts/python/nasal_api_doc.py

   1 #!/usr/bin/env python
   2 # -*- coding: utf-8 -*-
   3
   4 # Copyright (C) 2012 Adrian Musceac
   5 #
   6 # This program is free software: you can redistribute it and/or modify
   7 # it under the terms of the GNU General Public License as published by
   8 # the Free Software Foundation, either version 2 of the License, or
   9 # (at your option) any later version.
  10 #
  11 # This program is distributed in the hope that it will be useful,
  12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 # GNU General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License
  17 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18
  19
  20 import os, sys, glob
  21 import io
  22 import re, string
  23
  24 """Script which generates an API documentation file for Nasal libraries
  25 located inside $FGROOT/Nasal/
  26 Usage: nasal_api.py parse [path to $FGROOT/Nasal/]
  27 Or configure the local path below, and ommit the path in the console.
  28 The API doc in HTML format is generated in the current working directory"""
  29
  30 ########### Local $FGROOT/Nasal/ path ##########
  31 NASAL_PATH="../fgfs/fgdata/Nasal/"
  32
  33
  34 def get_files(nasal_dir):
  35         if nasal_dir[-1]!='/':
  36                 nasal_dir+='/'
  37         try:
  38                 os.stat(nasal_dir)
  39         except:
  40                 print "The path does not exist"
  41                 sys.exit()
  42         fgroot_dir = nasal_dir.rstrip('/').replace('Nasal','')
  43         f_version = open(fgroot_dir+'version','rb')
  44         version = f_version.read(256).rstrip('\n')
  45         top_level = []
  46         modules = []
  47         top_namespaces = []
  48         files_list = os.listdir(nasal_dir)
  49         for f in files_list:
  50                 if f.find(".nas")!=-1:
  51                         top_level.append(f)
  52                         continue
  53                 if os.path.isdir(nasal_dir + f):
  54                         modules.append(f)
  55         top_level.sort()
  56         modules.sort()
  57         if len(top_level) ==0:
  58                 print "This does not look like the correct $FGROOT/Nasal path"
  59                 sys.exit()
  60         if len(modules)==0:
  61                 print "Warning: could not find any submodules"
  62         for f in top_level:
  63                 namespace=f.replace(".nas","")
  64                 functions=parse_file(nasal_dir + f)
  65                 top_namespaces.append([namespace,functions])
  66         for m in modules:
  67                 files=glob.glob(nasal_dir+m+"/*.nas")
  68                 for f in files:
  69                         functions=parse_file(f)
  70                         top_namespaces.append([m,functions])
  71
  72         output_text(top_namespaces,modules,version)
  73
  74
  75 def output_text(top_namespaces,modules,version):
  76         fw=open('./nasal_api.html','wb')
  77         buf='<html><head>\
  78         <title>Nasal API</title>\
  79         <style>\n\
  80         a.main_module_link {margin-left:30px;display:block;float:left;}\
  81         div.container {background-color:#eee;clear:left;margin-top:20px;}\
  82         h2.namespace_title {padding-left:20px;color:#fff;background-color:#8888AC}\
  83         h4.class_function {padding-left:20px;background-color:#eee;color:#000033}\
  84         h4.class_definition {padding-left:20px;background-color:#eee;color:#000033}\
  85         h4.function {padding-left:20px;background-color:#eee;color:#000033}\
  86         hr {margin-left:30px;margin-right:30px;}\
  87         div.comments {padding-left:40px;display:inline;font-size:12px;}\
  88         </style>\n\
  89         </head><body style="width:1024px;">'
  90
  91         buf+='<h1 style="padding-left:20px;display:block;color:#fff;background-color:#555588;">\
  92         Nasal $FGROOT Library<br/><span style="font-size:12px;">Flightgear version: '+version+'\
  93         <br/>This file is generated automatically by scripts/python/nasal_api.py\
  94         </span></h1>\
  95         <br/><a href="http://plausible.org/nasal">Nasal documentation</a>&nbsp;&nbsp;\
  96         <a href="http://wiki.flightgear.org/Nasal_scripting_language">Flightgear Nasal documentation</a>\n<div style="float:right;">&nbsp;'
  97         buf+='<h2 style="font-size:14px;height:450px;width:250px;overflow:scroll;display:block;position:fixed;top:20px;right:20px;background-color:#8888AC;border:1px solid black;">\n'
  98         done=[]
  99         for namespace in top_namespaces:
 100                 color='0000cc'
 101                 if namespace[0] in modules:
 102                         color='cc0000'
 103                 if namespace[0] not in done:
 104                         buf+='<a class="main_module_link" style="color:'+color+'" href="#'+namespace[0]+'">'+namespace[0]+'</a>&nbsp;<br/>\n'
 105                         done.append(namespace[0])
 106         buf+='</h2></div>\n'
 107         done2=[]
 108         for namespace in top_namespaces:
 109                 if namespace[0] not in done2:
 110                         buf+='<div class="container" style="">\n'
 111                         buf += '<h2 class="namespace_title"><a name="'+namespace[0]+'">'+namespace[0]+'</a></h2>\n'
 112                         done2.append(namespace[0])
 113                 for functions in namespace[1]:
 114                         class_func=functions[0].split('.')
 115                         if len(class_func)>1:
 116                                 f_name=''
 117                                 if class_func[1].find('_')==0:
 118                                         f_name='<font color="#0000cc">'+class_func[1]+'</font>'
 119                                 else:
 120                                         f_name=class_func[1]
 121                                 if class_func[1]!='':
 122                                         buf+= '<div><h4 class="class_function"><b>'\
 123                                                 +namespace[0]+'</b>'+ "." + '<b><i>'+class_func[0]+'</i></b>'+'<b>.'+f_name+'</b>'+' ( <font color="#cc0000">'+ functions[1]+ '</font> )' +'</h4>\n'
 124                                 else:
 125                                         buf+= '<div><h4 class="class_definition"><b>'\
 126                                                 +namespace[0]+'</b>'+ "." + '<b><i><u><font color="#000000">'+class_func[0]+'</font></u></i></b>' +'</h4>\n'
 127                         else:
 128                                 if functions[0].find('_')==0:
 129                                         f_name='<font color="#0000cc">'+functions[0]+'</font>'
 130                                 else:
 131                                         f_name=functions[0]
 132                                 buf+= '<div><h4 class="function"><b>'\
 133                                         +namespace[0]+'</b>'+ "." + '<b>'+f_name+'</b>'+ ' ( <font color="#cc0000">'+ functions[1]+ '</font> )' +'</h4>\n'
 134                         for comment in functions[2]:
 135                                 if comment.find('=====')!=-1:
 136                                         buf+='<hr/>'
 137                                 else:
 138                                         buf+= '<div class="comments">'+comment.replace('#','').replace('<','&lt;').replace('>','&gt;')+'</div><br/>\n'
 139                         buf+='</div>\n'
 140                 if namespace[0] not in done2:
 141                         buf+='</div>\n'
 142         buf+='</body></html>'
 143         fw.write(buf)
 144         fw.close()
 145
 146 def parse_file(filename):
 147         fr=open(filename,'rb')
 148         content=fr.readlines()
 149         i=0
 150         retval=[]
 151         classname=""
 152         for line in content:
 153                 match=re.search('^var\s+([A-Za-z0-9_-]+)\s*=\s*func\s*\(?([A-Za-z0-9_\s,=.\n-]*)\)?',line)
 154                 if match!=None:
 155                         func_name=match.group(1)
 156                         comments=[]
 157                         param=match.group(2)
 158                         if(line.find(')')==-1 and line.find('(')!=-1):
 159                                 k=i+1
 160                                 while(content[k].find(')')==-1):
 161                                         param+=content[k].rstrip('\n')
 162                                         k+=1
 163                                 param+=content[k].split(')')[0]
 164                         j=i-1
 165                         count=0
 166                         while ( j>i-35 and j>-1):
 167                                 if count>3:
 168                                         break
 169                                 if len(content[j])<2:
 170                                         j-=1
 171                                         count+=1
 172                                         continue
 173                                 if re.search('^\s*#',content[j])!=None:
 174                                         comments.append(content[j].rstrip('\n'))
 175                                         j-=1
 176                                 else:
 177                                         break
 178                         if(len(comments)>1):
 179                                 comments.reverse()
 180                         retval.append((func_name, param,comments))
 181                         i+=1
 182                         continue
 183
 184                 match3=re.search('^var\s*([A-Za-z0-9_-]+)\s*=\s*{\s*(\n|})',line)
 185                 if match3!=None:
 186                         classname=match3.group(1)
 187
 188                         comments=[]
 189
 190                         j=i-1
 191                         count=0
 192                         while ( j>i-35 and j>-1):
 193                                 if count>3:
 194                                         break
 195                                 if len(content[j])<2:
 196                                         j-=1
 197                                         count+=1
 198                                         continue
 199                                 if re.search('^\s*#',content[j])!=None:
 200                                         comments.append(content[j].rstrip('\n'))
 201                                         j-=1
 202                                 else:
 203                                         break
 204                         if(len(comments)>1):
 205                                 comments.reverse()
 206                         retval.append((classname+'.', '',comments))
 207                         i+=1
 208                         continue
 209
 210                 match2=re.search('^\s*([A-Za-z0-9_-]+)\s*:\s*func\s*\(?([A-Za-z0-9_\s,=.\n-]*)\)?',line)
 211                 if match2!=None:
 212                         func_name=match2.group(1)
 213                         comments=[]
 214                         param=match2.group(2)
 215                         if(line.find(')')==-1 and line.find('(')!=-1):
 216                                 k=i+1
 217                                 while(content[k].find(')')==-1):
 218                                         param+=content[k].rstrip('\n')
 219                                         k+=1
 220                                 param+=content[k].split(')')[0]
 221                         j=i-1
 222                         count=0
 223                         while ( j>i-35 and j>-1):
 224                                 if count>3:
 225                                         break
 226                                 if len(content[j])<2:
 227                                         j-=1
 228                                         count+=1
 229                                         continue
 230                                 if re.search('^\s*#',content[j])!=None:
 231                                         comments.append(content[j].rstrip('\n'))
 232                                         j-=1
 233                                 else:
 234                                         break
 235                         if(len(comments)>1):
 236                                 comments.reverse()
 237                         if classname =='':
 238                                 continue
 239                         retval.append((classname+'.'+func_name, param,comments))
 240                         i+=1
 241                         continue
 242
 243                 match4=re.search('^([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]+)\s*=\s*func\s*\(?([A-Za-z0-9_\s,=\n.-]*)\)?',line)
 244                 if match4!=None:
 245                         classname=match4.group(1)
 246                         func_name=match4.group(2)
 247                         comments=[]
 248                         param=match4.group(3)
 249                         if(line.find(')')==-1 and line.find('(')!=-1):
 250                                 k=i+1
 251                                 while(content[k].find(')')==-1):
 252                                         param+=content[k].rstrip('\n')
 253                                         k+=1
 254                                 param+=content[k].split(')')[0]
 255                         j=i-1
 256                         count=0
 257                         while ( j>i-35 and j>-1):
 258                                 if count>3:
 259                                         break
 260                                 if len(content[j])<2:
 261                                         j-=1
 262                                         count+=1
 263                                         continue
 264                                 if re.search('^\s*#',content[j])!=None:
 265                                         comments.append(content[j].rstrip('\n'))
 266                                         j-=1
 267                                 else:
 268                                         break
 269                         if(len(comments)>1):
 270                                 comments.reverse()
 271                         retval.append((classname+'.'+func_name, param,comments))
 272                         i+=1
 273                         continue
 274
 275                 i+=1
 276         return retval
 277
 278
 279
 280 if __name__ == "__main__":
 281         if len(sys.argv) <2:
 282                 print 'Usage: nasal_api.py parse [path to $FGROOT/Nasal/]'
 283                 sys.exit()
 284         else:
 285                 if sys.argv[1]=='parse':
 286                         if len(sys.argv) <3:
 287                                 nasal_path=NASAL_PATH
 288                         else:
 289                                 nasal_path=sys.argv[2]
 290                         get_files(nasal_path)
 291                 else:
 292                         print 'Usage: nasal_api.py parse [path to $FGROOT/Nasal/]'
 293                         sys.exit()