Merge pull request #3617 from akien-mga/pr-rst-converter

Enhance XML to reST converter

3 files changed, 94 insertions, 35 deletions

diff --git a/doc/Makefile b/doc/Makefile
index 286a5162af..d59c77063b 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -38,7 +38,7 @@ rst:
 	rm -rf $(OUTPUTDIR)/rst
 	mkdir -p $(OUTPUTDIR)/rst
 	pushd $(OUTPUTDIR)/rst
-	echo "TODO"
+	python2 $(TOOLSDIR)/makerst.py $(CLASSES)
 	popd
 
 textile:
diff --git a/doc/base/classes.xml b/doc/base/classes.xml
index 98fc4dd085..d24abe7c38 100644
--- a/doc/base/classes.xml
+++ b/doc/base/classes.xml
@@ -1247,6 +1247,10 @@
 		</constant>
 		<constant name="BUTTON_WHEEL_DOWN" value="5">
 		</constant>
+		<constant name="BUTTON_WHEEL_LEFT" value="6">
+		</constant>
+		<constant name="BUTTON_WHEEL_RIGHT" value="7">
+		</constant>
 		<constant name="BUTTON_MASK_LEFT" value="1">
 		</constant>
 		<constant name="BUTTON_MASK_RIGHT" value="2">
@@ -1545,6 +1549,22 @@
 		<constant name="PROPERTY_USAGE_DEFAULT" value="7">
 			Default usage (storage and editor).
 		</constant>
+		<constant name="METHOD_FLAG_NORMAL" value="1">
+		</constant>
+		<constant name="METHOD_FLAG_EDITOR" value="2">
+		</constant>
+		<constant name="METHOD_FLAG_NOSCRIPT" value="4">
+		</constant>
+		<constant name="METHOD_FLAG_CONST" value="8">
+		</constant>
+		<constant name="METHOD_FLAG_REVERSE" value="16">
+		</constant>
+		<constant name="METHOD_FLAG_VIRTUAL" value="32">
+		</constant>
+		<constant name="METHOD_FLAG_FROM_SCRIPT" value="64">
+		</constant>
+		<constant name="METHOD_FLAGS_DEFAULT" value="1">
+		</constant>
 		<constant name="TYPE_NIL" value="0">
 			Variable is of type nil (only applied for null).
 		</constant>
@@ -10642,6 +10662,8 @@ This approximation makes straight segments between each point, then subdivides t
 		<method name="get_csv_line" qualifiers="const">
 			<return type="StringArray">
 			</return>
+			<argument index="0" name="delim" type="String" default="&quot;,&quot;">
+			</argument>
 			<description>
 			</description>
 		</method>
@@ -20006,6 +20028,14 @@ returns:= "username=user&amp;password=pass"
 			<description>
 			</description>
 		</method>
+		<method name="set_thread_name">
+			<return type="int">
+			</return>
+			<argument index="0" name="name" type="String">
+			</argument>
+			<description>
+			</description>
+		</method>
 	</methods>
 	<constants>
 		<constant name="DAY_SUNDAY" value="0">
@@ -35998,14 +36028,6 @@ This method controls whether the position between two cached points is interpola
 			<description>
 			</description>
 		</method>
-		<method name="set_name">
-			<return type="Error">
-			</return>
-			<argument index="0" name="name" type="String">
-			</argument>
-			<description>
-			</description>
-		</method>
 	</methods>
 	<constants>
 		<constant name="PRIORITY_LOW" value="0">
@@ -37762,7 +37784,9 @@ This method controls whether the position between two cached points is interpola
 			</argument>
 			<argument index="1" name="button" type="Texture">
 			</argument>
-			<argument index="2" name="button_idx" type="int">
+			<argument index="2" name="button_idx" type="int" default="-1">
+			</argument>
+			<argument index="3" name="disabled" type="bool" default="false">
 			</argument>
 			<description>
 			</description>
@@ -37793,6 +37817,16 @@ This method controls whether the position between two cached points is interpola
 			<description>
 			</description>
 		</method>
+		<method name="is_button_disabled" qualifiers="const">
+			<return type="bool">
+			</return>
+			<argument index="0" name="column" type="int">
+			</argument>
+			<argument index="1" name="button_idx" type="int">
+			</argument>
+			<description>
+			</description>
+		</method>
 		<method name="set_tooltip">
 			<argument index="0" name="column" type="int">
 			</argument>
diff --git a/doc/tools/makerst.py b/doc/tools/makerst.py
index 5d97004e65..33e62adf6c 100644
--- a/doc/tools/makerst.py
+++ b/doc/tools/makerst.py
@@ -99,6 +99,22 @@ def make_class_list(class_list, columns):
 
 
 def rstize_text(text,cclass):
+
+	# Linebreak + tabs in the XML should become two line breaks
+	pos = 0
+	while True:
+		pos = text.find('\n', pos)
+		if pos == -1:
+			break
+
+		pre_text = text[:pos]
+		while text[pos+1] == '\t':
+			pos += 1
+		post_text = text[pos+1:]
+
+		text = pre_text + "\n\n" + post_text
+		pos += 2
+
 	pos = 0
 	while True:
 		pos = text.find('[', pos)
@@ -145,7 +161,11 @@ def rstize_text(text,cclass):
 			elif cmd == '/center':
 				tag_text = ''
 			elif cmd == 'br':
-				tag_text = '\n| '
+				# Make a new paragraph instead of a linebreak, rst is not so linebreak friendly
+				tag_text = '\n\n'
+				# Strip potential leading spaces
+				while post_text[0] == ' ':
+					post_text = post_text[1:]
 			elif cmd == 'i' or cmd == '/i':
 				tag_text = '*'
 			elif cmd == 'b' or cmd == '/b':
@@ -259,31 +279,34 @@ def make_method(
 		f.write(t+s+"\n")
 
 
+def make_heading(title, underline):
+	return title + '\n' + underline*len(title) + "\n\n"
+
+
 def make_rst_class(node):
 
 	name = node.attrib['name']
 
 	f = open("class_"+name.lower() + '.rst', 'wb')
 
-	f.write(".. _class_"+name+":\n")
-	f.write(name + '  \n==========\n')
+	f.write(".. _class_"+name+":\n\n")
+	f.write(make_heading(name, '='))
 
 	if 'inherits' in node.attrib:
 		inh = node.attrib['inherits'].strip()
-		f.write('**Inherits:** '+make_type(inh)+'\n---------\n')
+		f.write(make_heading('Inherits: ' + make_type(inh), '-'))
 	if 'category' in node.attrib:
-		f.write('**Category:** ' + node.attrib['category'].strip()
-				+ '\n---------\n')
+		f.write(make_heading('Category: ' + node.attrib['category'].strip(), '-'))
 
 	briefd = node.find('brief_description')
 	if briefd != None:
-		f.write('\n Brief Description  \n-------\n')
-		f.write(rstize_text(briefd.text.strip(),name) + '\n')
+		f.write(make_heading('Brief Description', '-'))
+		f.write(rstize_text(briefd.text.strip(),name) + "\n\n")
 
 	methods = node.find('methods')
 
 	if methods != None and len(list(methods)) > 0:
-		f.write('\nMember Functions \n---------\n')
+		f.write(make_heading('Member Functions', '-'))
 		ml=[]
 		for m in list(methods):
 			make_method(f, node.attrib['name'], m, False,name,False,ml)
@@ -314,19 +337,19 @@ def make_rst_class(node):
 				st+=" "
 			f.write("| "+rt+" | "+st+" |\n")
 			f.write(sep)
-			
-		
+		f.write('\n')
+
 
 	events = node.find('signals')
 	if events != None and len(list(events)) > 0:
-		f.write('\nSignals  \n----------\n')
+		f.write(make_heading('Signals', '-'))
 		for m in list(events):
 			make_method(f, node.attrib['name'], m, True,name, True)
+		f.write('\n')
 
 	members = node.find('members')
-
 	if members != None and len(list(members)) > 0:
-		f.write('\nMember Variables  \n--------\n')
+		f.write(make_heading('Member Variables', '-'))
 
 		for c in list(members):
 			s = '- '
@@ -335,39 +358,41 @@ def make_rst_class(node):
 			if c.text.strip() != '':
 				s += ' - ' + c.text.strip()
 			f.write(s + '\n')
+		f.write('\n')
 
 	constants = node.find('constants')
 	if constants != None and len(list(constants)) > 0:
-		f.write('\nNumeric Constants  \n------\n')
+		f.write(make_heading('Numeric Constants', '-'))
 		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()
+				s += ' --- ' + rstize_text(c.text.strip(),name)
 			f.write(s + '\n')
+		f.write('\n')
 
 	descr = node.find('description')
 	if descr != None and descr.text.strip() != '':
-		f.write('\nDescription  \n-------\n')
-		f.write(rstize_text(descr.text.strip(),name) + '\n')
+		f.write(make_heading('Description', '-'))
+		f.write(rstize_text(descr.text.strip(),name) + "\n\n")
 
 	methods = node.find('methods')
-
 	if methods != None and len(list(methods)) > 0:
-		f.write('\nMember Function Description  \n----------\n')
+		f.write(make_heading('Member Function Description', '-'))
 		for m in list(methods):
-			f.write("\n.. _class_"+name+"_"+m.attrib['name']+":\n")
+			f.write(".. _class_"+name+"_"+m.attrib['name']+":\n\n")
 #			f.write(ul_string(m.attrib['name'],"^"))
-			d = m.find('description')
-			if d == None or d.text.strip() == '':
-				continue
 			#f.write('\n<a name="'+m.attrib['name']+'">' + m.attrib['name'] + '</a>\n------\n')
 			make_method(f, node.attrib['name'], m, True,name)
 			f.write('\n')
+			d = m.find('description')
+			if d == None or d.text.strip() == '':
+				continue
 			f.write(rstize_text(d.text.strip(),name))
-			f.write('\n')
+			f.write("\n\n")
+		f.write('\n')
 
 
 for file in input_list: