godotengine/godot
1
0
Fork 0
mirror of https://github.com/godotengine/godot.git synced 2025-11-17 14:11:06 +00:00
Code Releases Wiki Activity

Refactoring some strings and ordering imports

Browse Source
This commit is contained in:
Jorge Araya Navarro
2015-10-06 19:50:55 -06:00
parent 7a008afc67
commit 7c843fbc04
1 changed files with 52 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
tools/docdump/makedocs.py
View File

@@ -3,9 +3,7 @@
# #
# makedocs.py: Generate documentation for Open Project Wiki # makedocs.py: Generate documentation for Open Project Wiki
#
# Copyright (c) 2007-2015 Juan Linietsky, Ariel Manzur. # Copyright (c) 2007-2015 Juan Linietsky, Ariel Manzur.
#
# Contributor: Jorge Araya Navarro <elcorreo@deshackra.com> # Contributor: Jorge Araya Navarro <elcorreo@deshackra.com>
# #
@@ -24,7 +22,7 @@
# whitespace you may left. # whitespace you may left.
# #
# TODO: # TODO:
# * Refactor code. Refactor strings. # * Refactor code.
# * Adapt this script for generating content in other markup formats like # * Adapt this script for generating content in other markup formats like
# DokuWiki, Markdown, etc. # DokuWiki, Markdown, etc.
# * Because people will translate class_list.xml, we should implement # * Because people will translate class_list.xml, we should implement
@@ -32,17 +30,33 @@
# #
# Also check other TODO entries in this script for more information on what is # Also check other TODO entries in this script for more information on what is
# left to do. # left to do.
import re
import argparse import argparse
import logging import logging
from os import path import re
from itertools import zip_longest from itertools import zip_longest
from os import path
from xml.etree import ElementTree from xml.etree import ElementTree
# add an option to change the verbosity # add an option to change the verbosity
logging.basicConfig(level=logging.INFO) logging.basicConfig(level=logging.INFO)
# Strings
C_LINK = ("\"<code>{gclass}</code>(Go to page of class"
" {gclass})\":/class_{lkclass}")
MC_LINK = ("\"<code>{gclass}.{method}</code>(Go "
"to page {gclass}, section {method})\""
":/class_{lkclass}#{lkmethod}")
TM_JUMP = ("\"<code>{method}</code>(Jump to method"
" {method})\":#{lkmethod}")
GTC_LINK = " \"{rtype}(Go to page of class {rtype})\":/class_{link} "
DFN_JUMP = ("\"*{funcname}*(Jump to description for"
" node {funcname})\":#{link} <b>(</b> ")
M_ARG_DEFAULT = C_LINK + " {name}={default}"
M_ARG = C_LINK + " {name}"
OPENPROJ_INH = ("h4. Inherits: " + C_LINK + "\n\n")
def tb(string): def tb(string):
""" Return a byte representation of a string """ Return a byte representation of a string
@@ -69,9 +83,7 @@ def sortkey(c):
def toOP(text): def toOP(text):
""" Convert commands in text to Open Project commands """ Convert commands in text to Open Project commands
""" """
# We are going to do something very complicated with all HTML commands # TODO: Make this capture content between [command] ... [/command]
# sadly, some commands are embedded inside other commands, so some steps
# are needed before converting some commands to Textile markup
groups = re.finditer((r'\[html (?P<command>/?\w+/?)(\]| |=)?(\]| |=)?(?P<a' groups = re.finditer((r'\[html (?P<command>/?\w+/?)(\]| |=)?(\]| |=)?(?P<a'
'rg>\w+)?(\]| |=)?(?P<value>"[^"]+")?/?\]'), text) 'rg>\w+)?(\]| |=)?(?P<value>"[^"]+")?/?\]'), text)
alignstr = "" alignstr = ""
@@ -106,27 +118,21 @@ def toOP(text):
for group in groups: for group in groups:
gd = group.groupdict() gd = group.groupdict()
if gd["class"]: if gd["class"]:
replacewith = ("\"<code>{gclass}.{method}</code>(Go " replacewith = (MC_LINK.format(gclass=gd["class"],
"to page {gclass}, section {method})\"" method=gd["method"],
":/class_{lkclass}#{lkmethod}". lkclass=gd["class"].lower(),
format(gclass=gd["class"], lkmethod=gd["method"].lower()))
method=gd["method"],
lkclass=gd["class"].lower(),
lkmethod=gd["method"].lower()))
else: else:
# The method is located in the same wiki page # The method is located in the same wiki page
replacewith = ("\"<code>{method}</code>(Jump to method" replacewith = (TM_JUMP.format(method=gd["method"],
" {method})\":#{lkmethod}". lkmethod=gd["method"].lower()))
format(method=gd["method"],
lkmethod=gd["method"].lower()))
text = text.replace(group.group(0), replacewith, 1) text = text.replace(group.group(0), replacewith, 1)
# Finally, [Classes] are around brackets, make them direct links # Finally, [Classes] are around brackets, make them direct links
groups = re.finditer(r'\[(?P<class>[az0-AZ0_]+)\]', text) groups = re.finditer(r'\[(?P<class>[az0-AZ0_]+)\]', text)
for group in groups: for group in groups:
gd = group.groupdict() gd = group.groupdict()
replacewith = ("\"<code>{gclass}</code>(Go to page of class" replacewith = (C_LINK.
" {gclass})\":/class_{lkclass}".
format(gclass=gd["class"], format(gclass=gd["class"],
lkclass=gd["class"].lower())) lkclass=gd["class"].lower()))
text = text.replace(group.group(0), replacewith, 1) text = text.replace(group.group(0), replacewith, 1)
@@ -149,18 +155,16 @@ def mkfn(node, is_signal=False):
# return type # return type
if not is_signal: if not is_signal:
if rtype != "void": if rtype != "void":
finalstr += " \"{rtype}({title})\":/class_{link} ".format( finalstr += GTC_LINK.format(
rtype=rtype, rtype=rtype,
title="Go to page of class " + rtype,
link=rtype.lower()) link=rtype.lower())
else: else:
finalstr += " void " finalstr += " void "
# function name # function name
if not is_signal: if not is_signal:
finalstr += "\"*{funcname}*({title})\":#{link} <b>(</b> ".format( finalstr += DFN_JUMP.format(
funcname=name, funcname=name,
title="Jump to description for node " + name,
link=name.lower()) link=name.lower())
else: else:
# Signals have no description # Signals have no description
@@ -171,31 +175,19 @@ def mkfn(node, is_signal=False):
node.iter(tag="argument"), node.iter(tag="argument"),
key=lambda a: int(a.attrib["index"])): key=lambda a: int(a.attrib["index"])):
twd = "{type} {name}={default}"
tnd = "{type} {name}"
tlk = ("\"*{cls}*(Go to page of class {cls})"
"\":/class_{lcls}")
ntype = arg.attrib["type"] ntype = arg.attrib["type"]
nname = arg.attrib["name"] nname = arg.attrib["name"]
if "default" in arg.attrib: if "default" in arg.attrib:
args.insert( args.insert(-1, M_ARG_DEFAULT.format(
-1, gclass=ntype,
twd.format( lkclass=ntype.lower(),
type=tlk.format( name=nname,
cls=ntype, default=arg.attrib["default"]))
lcls=ntype.lower()),
name=nname,
default=arg.attrib["default"]))
else: else:
# No default value present # No default value present
args.insert( args.insert(-1, M_ARG.format(gclass=ntype,
-1, lkclass=ntype.lower(), name=nname))
tnd.format(
type=tlk.format(
cls=ntype,
lcls=ntype.lower()),
name=nname))
# join the arguments together # join the arguments together
finalstr += ", ".join(args) finalstr += ", ".join(args)
# and, close the function with a ) # and, close the function with a )
@@ -265,10 +257,9 @@ with open(path.join(args.outputdir, "class_list.txt"), "wb") as fcl:
# empty cell # empty cell
fcl.write(tb("| |")) fcl.write(tb("| |"))
# write the class name column, left # write the class name column, left
fcl.write(tb("\"{name}({title})\":/class_{link}".format( fcl.write(tb(C_LINK.format(
name=gdclassl.attrib["name"], gclass=gdclassl.attrib["name"],
title="Go to page of class " + gdclassl.attrib["name"], lkclass=gdclassl.attrib["name"].lower())))
link="class_" + gdclassl.attrib["name"].lower())))
# write the index symbol column, right # write the index symbol column, right
if isinstance(gdclassr, ElementTree.Element): if isinstance(gdclassr, ElementTree.Element):
@@ -288,10 +279,9 @@ with open(path.join(args.outputdir, "class_list.txt"), "wb") as fcl:
continue continue
# write the class name column (if any), right # write the class name column (if any), right
fcl.write(tb("\"{name}({title})\":/{link} |\n".format( fcl.write(tb(C_LINK.format(
name=gdclassr.attrib["name"], gclass=gdclassl.attrib["name"],
title="Go to page of class " + gdclassr.attrib["name"], lkclass=gdclassl.attrib["name"].lower()) + "|\n"))
link=gdclassr.attrib["name"].lower())))
# row written # # row written #
# now, let's write each class page for each class # now, let's write each class page for each class
@@ -307,36 +297,28 @@ with open(path.join(args.outputdir, "class_list.txt"), "wb") as fcl:
# lay the attributes # lay the attributes
if "inherits" in gdclass.attrib: if "inherits" in gdclass.attrib:
inh = gdclass.attrib["inherits"].strip() inh = gdclass.attrib["inherits"].strip()
clsf.write(tb(("h4. Inherits: \"<code>{name}" clsf.write(tb(OPENPROJ_INH.format(gclass=inh,
"</code>({title})\":/class_{link}\n\n"). lkclass=inh.lower())))
format(
name=inh,
title="Go to page of class " + inh,
link=classname.lower())))
if "category" in gdclass.attrib: if "category" in gdclass.attrib:
clsf.write(tb("h4. Category: {}\n\n". clsf.write(tb("h4. Category: {}\n\n".
format(gdclass.attrib["category"].strip()))) format(gdclass.attrib["category"].strip())))
# lay child nodes # lay child nodes
briefd = gdclass.find("brief_description") briefd = gdclass.find("brief_description")
logging.debug(
"Brief description was found?: {}".format(briefd))
if briefd.text.strip(): if briefd.text.strip():
logging.debug( clsf.write(b"h2. Brief Description\n\n")
"Text: {}".format(briefd.text.strip()))
clsf.write(tb("h2. Brief Description\n\n"))
clsf.write(tb(toOP(briefd.text.strip()) + clsf.write(tb(toOP(briefd.text.strip()) +
"\"read more\":#more\n\n")) "\"read more\":#more\n\n"))
# Write the list of member functions of this class # Write the list of member functions of this class
methods = gdclass.find("methods") methods = gdclass.find("methods")
if methods and len(methods) > 0: if methods and len(methods) > 0:
clsf.write(tb("\nh3. Member Functions\n\n")) clsf.write(b"\nh3. Member Functions\n\n")
for method in methods.iter(tag='method'): for method in methods.iter(tag='method'):
clsf.write(tb(mkfn(method))) clsf.write(tb(mkfn(method)))
signals = gdclass.find("signals") signals = gdclass.find("signals")
if signals and len(signals) > 0: if signals and len(signals) > 0:
clsf.write(tb("\nh3. Signals\n\n")) clsf.write(b"\nh3. Signals\n\n")
for signal in signals.iter(tag='signal'): for signal in signals.iter(tag='signal'):
clsf.write(tb(mkfn(signal, True))) clsf.write(tb(mkfn(signal, True)))
# TODO: <members> tag is necessary to process? it does not # TODO: <members> tag is necessary to process? it does not
@@ -344,7 +326,7 @@ with open(path.join(args.outputdir, "class_list.txt"), "wb") as fcl:
consts = gdclass.find("constants") consts = gdclass.find("constants")
if consts and len(consts) > 0: if consts and len(consts) > 0:
clsf.write(tb("\nh3. Numeric Constants\n\n")) clsf.write(b"\nh3. Numeric Constants\n\n")
for const in sorted(consts, key=lambda k: for const in sorted(consts, key=lambda k:
k.attrib["name"]): k.attrib["name"]):
if const.text.strip(): if const.text.strip():
@@ -360,15 +342,15 @@ with open(path.join(args.outputdir, "class_list.txt"), "wb") as fcl:
name=const.attrib["name"], name=const.attrib["name"],
value=const.attrib["value"]))) value=const.attrib["value"])))
descrip = gdclass.find("description") descrip = gdclass.find("description")
clsf.write(tb("\nh3(#more). Description\n\n")) clsf.write(b"\nh3(#more). Description\n\n")
if descrip.text: if descrip.text:
clsf.write(tb(descrip.text.strip() + "\n")) clsf.write(tb(descrip.text.strip() + "\n"))
else: else:
clsf.write(tb("_Nothing here, yet..._\n")) clsf.write(b"_Nothing here, yet..._\n")
# and finally, the description for each method # and finally, the description for each method
if methods and len(methods) > 0: if methods and len(methods) > 0:
clsf.write(tb("\nh3. Member Function Description\n\n")) clsf.write(b"\nh3. Member Function Description\n\n")
for method in methods.iter(tag='method'): for method in methods.iter(tag='method'):
clsf.write(tb("h4(#{n}). {name}\n\n".format( clsf.write(tb("h4(#{n}). {name}\n\n".format(
n=method.attrib["name"].lower(), n=method.attrib["name"].lower(),