godot/doc/tools/makedoku.py

#!/usr/bin/python
# -*- coding: utf-8 -*-

import sys
import xml.etree.ElementTree as ET

input_list = []


for arg in sys.argv[1:]:
  input_list.append(arg)

if len(input_list) < 1:
  print("usage: makedoku.py <classes.xml>")
  sys.exit(0)


def validate_tag(elem,tag):
  if (elem.tag != tag):
    print("Tag mismatch, expected '"+tag+"', got "+elem.tag);
    sys.exit(255)
 

class_names=[]
classes={}


def make_class_list(class_list,columns):
	
	f=open("class_list.txt","wb")
	prev=0
	col_max = len(class_list) / columns + 1
	print("col max is ", col_max)
	col_count = 0
	row_count = 0
	last_initial = ""
	fit_columns=[]
  
	for n in range(0,columns):
		fit_columns+=[[]]

	indexers=[]
	last_initial=""
     
	idx=0
	for n in class_list:
		col = idx/col_max
		if (col>=columns):
			col=columns-1
		fit_columns[col]+=[n]
		idx+=1
		if (n[:1]!=last_initial):
			indexers+=[n]
		last_initial=n[:1]
		

	row_max=0
  
	for n in range(0,columns):
		if (len(fit_columns[n])>row_max):
			row_max=len(fit_columns[n])
    

	for r in range(0,row_max):
		s="|"
		for c in range(0,columns):   
			if (r>=len(fit_columns[c])):
				continue
    
			classname = fit_columns[c][r]
			initial=classname[0]
			if (classname in indexers):
				s+="**"+initial+"**|"
			else:
				s+=" |"
				
			s+="[["+classname.lower()+"|"+classname+"]]|"
			
		s+="\n"
		f.write(s)
	
	
def dokuize_text(txt):
	
	return txt


def dokuize_text(text):
 pos=0
 while(True):
  pos = text.find("[",pos)
  if (pos==-1):
   break

  endq_pos=text.find("]",pos+1)
  if (endq_pos==-1):
   break
    
  pre_text=text[:pos]
  post_text=text[endq_pos+1:]
  tag_text=text[pos+1:endq_pos]

  if (tag_text in class_names):
    tag_text="[["+tag_text.lower()+"|"+tag_text+"]]"   
  else: #command
   cmd=tag_text
   space_pos=tag_text.find(" ")
   if (cmd.find("html")==0):
    cmd=tag_text[:space_pos]
    param=tag_text[space_pos+1:]
    tag_text="<"+param+">"
   elif(cmd.find("method")==0):
    cmd=tag_text[:space_pos]
    param=tag_text[space_pos+1:]
    
    if (param.find(".")!=-1):
     class_param,method_param=param.split(".")
     tag_text="[["+class_param.lower()+"#"+method_param+"|"+class_param+'.'+method_param+"]]"
    else:
     tag_text="[[#"+param+"|"+param+"]]"
   elif (cmd.find("image=")==0):
    tag_text="{{"+cmd[6:]+"}}"
   elif (cmd.find("url=")==0):
    tag_text="[["+cmd[4:]+"|"
   elif (cmd=="/url"):
    tag_text="]]>" 
   elif (cmd=="center"):
    tag_text=""
   elif (cmd=="/center"):
    tag_text=""
   elif (cmd=="br"):
    tag_text="\\\\\n"
   elif (cmd=="i" or cmd=="/i"):
    tag_text="//"
   elif (cmd=="b" or cmd=="/b"):
    tag_text="**"
   elif (cmd=="u" or cmd=="/u"):
    tag_text="__"
   else:
    tag_text="["+tag_text+"]"
   
 
  text=pre_text+tag_text+post_text
  pos=len(pre_text)+len(tag_text)
  
 #tnode = ET.SubElement(parent,"div")
 #tnode.text=text
 return text
 	
	
def make_type(t):
	global class_names
	if (t in class_names):
		return "[["+t.lower()+"|"+t+"]]"
	return t
	
	
def make_method(f,name,m,declare,event=False):
	
	s="  * "
	ret_type="void"
	args=list(m)
	mdata={}
	mdata["argidx"]=[]
	for a in args:
		if (a.tag=="return"):
			idx=-1
		elif (a.tag=="argument"):
			idx=int(a.attrib["index"])
		else:
			continue
   
		mdata["argidx"].append(idx)
		mdata[idx]=a
		
	

	if (not event):  
		if (-1 in mdata["argidx"]):
			s+=make_type(mdata[-1].attrib["type"])
		else: 
			s+="void"
		s+=" "
		
	if (declare):
		
		#span.attrib["class"]="funcdecl"
		#a=ET.SubElement(span,"a")
		#a.attrib["name"]=name+"_"+m.attrib["name"]
		#a.text=name+"::"+m.attrib["name"]
		s+="**"+m.attrib["name"]+"**"
	else:		
		s+="[[#"+m.attrib["name"]+"|"+m.attrib["name"]+"]]"
		
	s+="**(**"
	argfound=False
	for a in mdata["argidx"]:
		arg=mdata[a]
		if (a<0):
			continue
		if (a>0):  
			s+=", "
		else:
			s+=" "
		
		s+=make_type(arg.attrib["type"])
		if ("name" in arg.attrib):
			s+=" "+arg.attrib["name"]
		else:
			s+=" arg"+str(a)
		
		if ("default" in arg.attrib):
			s+="="+arg.attrib["default"]
		
		
		argfound=True
		
	if (argfound):
		s+=" "
	s+="**)**"
		
	if ("qualifiers" in m.attrib):
		s+=" "+m.attrib["qualifiers"]
		
	f.write(s+"\n")
	
  
def make_doku_class(node):

	name = node.attrib["name"]
	
	f=open(name.lower()+".txt","wb")

	f.write("======  "+name+"  ======\n")

	if ("inherits" in node.attrib):
		inh=node.attrib["inherits"].strip()
		f.write("**Inherits:** [["+inh.lower()+"|"+inh+"]]\\\\\n")
	if ("category" in node.attrib):
		f.write("**Category:** "+node.attrib["category"].strip()+"\\\\\n")
	
	briefd = node.find("brief_description")
	if (briefd!=None):
		f.write("=====  Brief Description  ======\n")
		f.write( dokuize_text(briefd.text.strip())+"\n" )
	
	methods = node.find("methods")  
  
	if(methods!=None and len(list(methods))>0):
		f.write("=====  Member Functions  ======\n")
		for m in list(methods):
			make_method(f,node.attrib["name"],m,False)
		
	events = node.find("signals")  
	if(events!=None and len(list(events))>0):	
		f.write("=====  Signals  ======\n")
		for m in list(events):
			make_method(f,node.attrib["name"],m,True,True)
			
	members = node.find("members")  

	if(members!=None and len(list(members))>0):
		f.write("=====  Member Variables  ======\n")

		for c in list(members):
			s = "  * "
			s+=make_type(c.attrib["type"])+" "
			s+="**"+c.attrib["name"]+"**"
			if (c.text.strip()!=""):
				s+=" - "+c.text.strip()
			f.write(s+"\n")
				
	
			
	constants = node.find("constants")  
	if(constants!=None and len(list(constants))>0):
		f.write("=====  Numeric Constants  ======\n")
		for c in list(constants):
			s = "  * "
			s+="**"+c.attrib["name"]+"**"
			if ("value" in c.attrib):
				s+=" = **"+c.attrib["value"]+"**"			
			if (c.text.strip()!=""):
				s+=" - "+c.text.strip()
			f.write(s+"\n")
			
		
	descr=node.find("description")
	if (descr!=None and descr.text.strip()!=""):
		f.write("=====  Description  ======\n")
		f.write(dokuize_text(descr.text.strip())+"\n")

	methods = node.find("methods")  
		
	if(methods!=None and len(list(methods))>0):
		f.write("=====  Member Function Description  ======\n")
		for m in list(methods):
			
			d=m.find("description")
			if (d==None or d.text.strip()==""):
				continue
			f.write("==  "+m.attrib["name"]+"  ==\n")
			make_method(f,node.attrib["name"],m,False)
			f.write("\\\\\n")
			f.write(dokuize_text(d.text.strip()))
			f.write("\n")
			
			
				

			
	"""
  div=ET.Element("div")
  div.attrib["class"]="class";

  a=ET.SubElement(div,"a")
  a.attrib["name"]=node.attrib["name"]
  
  h3=ET.SubElement(a,"h3")
  h3.attrib["class"]="title class_title"
  h3.text=node.attrib["name"]

  briefd = node.find("brief_description")
  if (briefd!=None):
   div2=ET.SubElement(div,"div")
   div2.attrib["class"]="description class_description"
   div2.text=briefd.text
   
  if ("inherits" in node.attrib):
   ET.SubElement(div,"br")

   div2=ET.SubElement(div,"div")   
   div2.attrib["class"]="inheritance";

   span=ET.SubElement(div2,"span")
   span.text="Inherits: "
   
   make_type(node.attrib["inherits"],div2)
   
  if ("category" in node.attrib):
   ET.SubElement(div,"br")
   
   div3=ET.SubElement(div,"div")   
   div3.attrib["class"]="category";
    
   span=ET.SubElement(div3,"span")
   span.attrib["class"]="category"
   span.text="Category: "
    
   a = ET.SubElement(div3,"a")
   a.attrib["class"]="category_ref"
   a.text=node.attrib["category"]
   catname=a.text
   if (catname.rfind("/")!=-1):
    catname=catname[catname.rfind("/"):] 
   catname="CATEGORY_"+catname
    
   if (single_page):
    a.attrib["href"]="#"+catname
   else:
    a.attrib["href"]="category.html#"+catname
    
    
  methods = node.find("methods")  
  
  if(methods!=None and len(list(methods))>0):

   h4=ET.SubElement(div,"h4")
   h4.text="Public Methods:"

   method_table=ET.SubElement(div,"table")   
   method_table.attrib["class"]="method_list";

   for m in list(methods):
#    li = ET.SubElement(div2, "li")
    method_table.append( make_method_def(node.attrib["name"],m,False) )

  events = node.find("signals")  
  
  if(events!=None and len(list(events))>0):
   h4=ET.SubElement(div,"h4")
   h4.text="Events:"

   event_table=ET.SubElement(div,"table")   
   event_table.attrib["class"]="method_list";

   for m in list(events):
#    li = ET.SubElement(div2, "li")
    event_table.append( make_method_def(node.attrib["name"],m,False,True) )


  members = node.find("members")  
  if(members!=None and len(list(members))>0):

   h4=ET.SubElement(div,"h4")
   h4.text="Public Variables:"
   div2=ET.SubElement(div,"div")   
   div2.attrib["class"]="member_list";
   
   for c in list(members):
   
    li = ET.SubElement(div2, "li")
    div3=ET.SubElement(li,"div")
    div3.attrib["class"]="member";
    make_type(c.attrib["type"],div3)    
    span=ET.SubElement(div3,"span")
    span.attrib["class"]="identifier member_name"
    span.text=" "+c.attrib["name"]+" "
    span=ET.SubElement(div3,"span")
    span.attrib["class"]="member_description"
    span.text=c.text


  constants = node.find("constants")  
  if(constants!=None and len(list(constants))>0):

   h4=ET.SubElement(div,"h4")
   h4.text="Constants:"
   div2=ET.SubElement(div,"div")   
   div2.attrib["class"]="constant_list";
   
   for c in list(constants):
    li = ET.SubElement(div2, "li")
    div3=ET.SubElement(li,"div")
    div3.attrib["class"]="constant";
    
    span=ET.SubElement(div3,"span")
    span.attrib["class"]="identifier constant_name"
    span.text=c.attrib["name"]+" "
    if ("value" in c.attrib):
     span=ET.SubElement(div3,"span")
     span.attrib["class"]="symbol"
     span.text="= "
     span=ET.SubElement(div3,"span")
     span.attrib["class"]="constant_value"
     span.text=c.attrib["value"]+" "
    span=ET.SubElement(div3,"span")
    span.attrib["class"]="constant_description"
    span.text=c.text
     
#  ET.SubElement(div,"br")
   
  
  descr=node.find("description")
  if (descr!=None and descr.text.strip()!=""):

   h4=ET.SubElement(div,"h4")
   h4.text="Description:"
  
   make_text_def(node.attrib["name"],div,descr.text)
#   div2=ET.SubElement(div,"div")   
#   div2.attrib["class"]="description";
#   div2.text=descr.text
  
  
  
  if(methods!=None or events!=None):

   h4=ET.SubElement(div,"h4")
   h4.text="Method Documentation:"
   iter_list = []
   if (methods!=None):
    iter_list+=list(methods)
   if (events!=None):
    iter_list+=list(events)

   for m in iter_list:

    descr=m.find("description")
                 
    if (descr==None or descr.text.strip()==""):
     continue;

    div2=ET.SubElement(div,"div")
    div2.attrib["class"]="method_doc";


    div2.append( make_method_def(node.attrib["name"],m,True) )
	#anchor = ET.SubElement(div2, "a")
	#anchor.attrib["name"] =
    make_text_def(node.attrib["name"],div2,descr.text)
    #div3=ET.SubElement(div2,"div")   
    #div3.attrib["class"]="description";
    #div3.text=descr.text
     
  
  return div
"""
for file in input_list:
	tree = ET.parse(file)
	doc=tree.getroot()

	if ("version" not in doc.attrib):
		print("Version missing from 'doc'")
		sys.exit(255)

	version=doc.attrib["version"]

	for c in list(doc):
		if (c.attrib["name"] in class_names):
			continue
		class_names.append(c.attrib["name"])
		classes[c.attrib["name"]]=c
		

class_names.sort()
  
make_class_list(class_names,4)

for cn in class_names:
	c=classes[cn]
	make_doku_class(c)