makerst.py 38 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026
  1. #!/usr/bin/env python3
  2. import argparse
  3. import os
  4. import re
  5. import xml.etree.ElementTree as ET
  6. from collections import OrderedDict
  7. # Uncomment to do type checks. I have it commented out so it works below Python 3.5
  8. #from typing import List, Dict, TextIO, Tuple, Iterable, Optional, DefaultDict, Any, Union
  9. # http(s)://docs.godotengine.org/<langcode>/<tag>/path/to/page.html(#fragment-tag)
  10. GODOT_DOCS_PATTERN = re.compile(r'^http(?:s)?://docs\.godotengine\.org/(?:[a-zA-Z0-9.\-_]*)/(?:[a-zA-Z0-9.\-_]*)/(.*)\.html(#.*)?$')
  11. def print_error(error, state): # type: (str, State) -> None
  12. print(error)
  13. state.errored = True
  14. class TypeName:
  15. def __init__(self, type_name, enum=None): # type: (str, Optional[str]) -> None
  16. self.type_name = type_name
  17. self.enum = enum
  18. def to_rst(self, state): # type: ("State") -> str
  19. if self.enum is not None:
  20. return make_enum(self.enum, state)
  21. elif self.type_name == "void":
  22. return "void"
  23. else:
  24. return make_type(self.type_name, state)
  25. @classmethod
  26. def from_element(cls, element): # type: (ET.Element) -> "TypeName"
  27. return cls(element.attrib["type"], element.get("enum"))
  28. class PropertyDef:
  29. def __init__(self, name, type_name, setter, getter, text, default_value, overridden): # type: (str, TypeName, Optional[str], Optional[str], Optional[str], Optional[str], Optional[bool]) -> None
  30. self.name = name
  31. self.type_name = type_name
  32. self.setter = setter
  33. self.getter = getter
  34. self.text = text
  35. self.default_value = default_value
  36. self.overridden = overridden
  37. class ParameterDef:
  38. def __init__(self, name, type_name, default_value): # type: (str, TypeName, Optional[str]) -> None
  39. self.name = name
  40. self.type_name = type_name
  41. self.default_value = default_value
  42. class SignalDef:
  43. def __init__(self, name, parameters, description): # type: (str, List[ParameterDef], Optional[str]) -> None
  44. self.name = name
  45. self.parameters = parameters
  46. self.description = description
  47. class MethodDef:
  48. def __init__(self, name, return_type, parameters, description, qualifiers): # type: (str, TypeName, List[ParameterDef], Optional[str], Optional[str]) -> None
  49. self.name = name
  50. self.return_type = return_type
  51. self.parameters = parameters
  52. self.description = description
  53. self.qualifiers = qualifiers
  54. class ConstantDef:
  55. def __init__(self, name, value, text): # type: (str, str, Optional[str]) -> None
  56. self.name = name
  57. self.value = value
  58. self.text = text
  59. class EnumDef:
  60. def __init__(self, name): # type: (str) -> None
  61. self.name = name
  62. self.values = OrderedDict() # type: OrderedDict[str, ConstantDef]
  63. class ThemeItemDef:
  64. def __init__(self, name, type_name, default_value): # type: (str, TypeName, Optional[str]) -> None
  65. self.name = name
  66. self.type_name = type_name
  67. self.default_value = default_value
  68. class ClassDef:
  69. def __init__(self, name): # type: (str) -> None
  70. self.name = name
  71. self.constants = OrderedDict() # type: OrderedDict[str, ConstantDef]
  72. self.enums = OrderedDict() # type: OrderedDict[str, EnumDef]
  73. self.properties = OrderedDict() # type: OrderedDict[str, PropertyDef]
  74. self.methods = OrderedDict() # type: OrderedDict[str, List[MethodDef]]
  75. self.signals = OrderedDict() # type: OrderedDict[str, SignalDef]
  76. self.inherits = None # type: Optional[str]
  77. self.category = None # type: Optional[str]
  78. self.brief_description = None # type: Optional[str]
  79. self.description = None # type: Optional[str]
  80. self.theme_items = None # type: Optional[OrderedDict[str, List[ThemeItemDef]]]
  81. self.tutorials = [] # type: List[str]
  82. class State:
  83. def __init__(self): # type: () -> None
  84. # Has any error been reported?
  85. self.errored = False
  86. self.classes = OrderedDict() # type: OrderedDict[str, ClassDef]
  87. self.current_class = "" # type: str
  88. def parse_class(self, class_root): # type: (ET.Element) -> None
  89. class_name = class_root.attrib["name"]
  90. class_def = ClassDef(class_name)
  91. self.classes[class_name] = class_def
  92. inherits = class_root.get("inherits")
  93. if inherits is not None:
  94. class_def.inherits = inherits
  95. category = class_root.get("category")
  96. if category is not None:
  97. class_def.category = category
  98. brief_desc = class_root.find("brief_description")
  99. if brief_desc is not None and brief_desc.text:
  100. class_def.brief_description = brief_desc.text
  101. desc = class_root.find("description")
  102. if desc is not None and desc.text:
  103. class_def.description = desc.text
  104. properties = class_root.find("members")
  105. if properties is not None:
  106. for property in properties:
  107. assert property.tag == "member"
  108. property_name = property.attrib["name"]
  109. if property_name in class_def.properties:
  110. print_error("Duplicate property '{}', file: {}".format(property_name, class_name), self)
  111. continue
  112. type_name = TypeName.from_element(property)
  113. setter = property.get("setter") or None # Use or None so '' gets turned into None.
  114. getter = property.get("getter") or None
  115. default_value = property.get("default") or None
  116. overridden = property.get("override") or False
  117. property_def = PropertyDef(property_name, type_name, setter, getter, property.text, default_value, overridden)
  118. class_def.properties[property_name] = property_def
  119. methods = class_root.find("methods")
  120. if methods is not None:
  121. for method in methods:
  122. assert method.tag == "method"
  123. method_name = method.attrib["name"]
  124. qualifiers = method.get("qualifiers")
  125. return_element = method.find("return")
  126. if return_element is not None:
  127. return_type = TypeName.from_element(return_element)
  128. else:
  129. return_type = TypeName("void")
  130. params = parse_arguments(method)
  131. desc_element = method.find("description")
  132. method_desc = None
  133. if desc_element is not None:
  134. method_desc = desc_element.text
  135. method_def = MethodDef(method_name, return_type, params, method_desc, qualifiers)
  136. if method_name not in class_def.methods:
  137. class_def.methods[method_name] = []
  138. class_def.methods[method_name].append(method_def)
  139. constants = class_root.find("constants")
  140. if constants is not None:
  141. for constant in constants:
  142. assert constant.tag == "constant"
  143. constant_name = constant.attrib["name"]
  144. value = constant.attrib["value"]
  145. enum = constant.get("enum")
  146. constant_def = ConstantDef(constant_name, value, constant.text)
  147. if enum is None:
  148. if constant_name in class_def.constants:
  149. print_error("Duplicate constant '{}', file: {}".format(constant_name, class_name), self)
  150. continue
  151. class_def.constants[constant_name] = constant_def
  152. else:
  153. if enum in class_def.enums:
  154. enum_def = class_def.enums[enum]
  155. else:
  156. enum_def = EnumDef(enum)
  157. class_def.enums[enum] = enum_def
  158. enum_def.values[constant_name] = constant_def
  159. signals = class_root.find("signals")
  160. if signals is not None:
  161. for signal in signals:
  162. assert signal.tag == "signal"
  163. signal_name = signal.attrib["name"]
  164. if signal_name in class_def.signals:
  165. print_error("Duplicate signal '{}', file: {}".format(signal_name, class_name), self)
  166. continue
  167. params = parse_arguments(signal)
  168. desc_element = signal.find("description")
  169. signal_desc = None
  170. if desc_element is not None:
  171. signal_desc = desc_element.text
  172. signal_def = SignalDef(signal_name, params, signal_desc)
  173. class_def.signals[signal_name] = signal_def
  174. theme_items = class_root.find("theme_items")
  175. if theme_items is not None:
  176. class_def.theme_items = OrderedDict()
  177. for theme_item in theme_items:
  178. assert theme_item.tag == "theme_item"
  179. theme_item_name = theme_item.attrib["name"]
  180. default_value = theme_item.get("default") or None
  181. theme_item_def = ThemeItemDef(theme_item_name, TypeName.from_element(theme_item), default_value)
  182. if theme_item_name not in class_def.theme_items:
  183. class_def.theme_items[theme_item_name] = []
  184. class_def.theme_items[theme_item_name].append(theme_item_def)
  185. tutorials = class_root.find("tutorials")
  186. if tutorials is not None:
  187. for link in tutorials:
  188. assert link.tag == "link"
  189. if link.text is not None:
  190. class_def.tutorials.append(link.text)
  191. def sort_classes(self): # type: () -> None
  192. self.classes = OrderedDict(sorted(self.classes.items(), key=lambda t: t[0]))
  193. def parse_arguments(root): # type: (ET.Element) -> List[ParameterDef]
  194. param_elements = root.findall("argument")
  195. params = [None] * len(param_elements) # type: Any
  196. for param_element in param_elements:
  197. param_name = param_element.attrib["name"]
  198. index = int(param_element.attrib["index"])
  199. type_name = TypeName.from_element(param_element)
  200. default = param_element.get("default")
  201. params[index] = ParameterDef(param_name, type_name, default)
  202. cast = params # type: List[ParameterDef]
  203. return cast
  204. def main(): # type: () -> None
  205. parser = argparse.ArgumentParser()
  206. parser.add_argument("path", nargs="+", help="A path to an XML file or a directory containing XML files to parse.")
  207. group = parser.add_mutually_exclusive_group()
  208. group.add_argument("--output", "-o", default=".", help="The directory to save output .rst files in.")
  209. group.add_argument("--dry-run", action="store_true", help="If passed, no output will be generated and XML files are only checked for errors.")
  210. args = parser.parse_args()
  211. file_list = [] # type: List[str]
  212. for path in args.path:
  213. # Cut off trailing slashes so os.path.basename doesn't choke.
  214. if path.endswith(os.sep):
  215. path = path[:-1]
  216. if os.path.basename(path) == 'modules':
  217. for subdir, dirs, _ in os.walk(path):
  218. if 'doc_classes' in dirs:
  219. doc_dir = os.path.join(subdir, 'doc_classes')
  220. class_file_names = (f for f in os.listdir(doc_dir) if f.endswith('.xml'))
  221. file_list += (os.path.join(doc_dir, f) for f in class_file_names)
  222. elif os.path.isdir(path):
  223. file_list += (os.path.join(path, f) for f in os.listdir(path) if f.endswith('.xml'))
  224. elif os.path.isfile(path):
  225. if not path.endswith(".xml"):
  226. print("Got non-.xml file '{}' in input, skipping.".format(path))
  227. continue
  228. file_list.append(path)
  229. classes = {} # type: Dict[str, ET.Element]
  230. state = State()
  231. for cur_file in file_list:
  232. try:
  233. tree = ET.parse(cur_file)
  234. except ET.ParseError as e:
  235. print_error("Parse error reading file '{}': {}".format(cur_file, e), state)
  236. continue
  237. doc = tree.getroot()
  238. if 'version' not in doc.attrib:
  239. print_error("Version missing from 'doc', file: {}".format(cur_file), state)
  240. continue
  241. name = doc.attrib["name"]
  242. if name in classes:
  243. print_error("Duplicate class '{}'".format(name), state)
  244. continue
  245. classes[name] = doc
  246. for name, data in classes.items():
  247. try:
  248. state.parse_class(data)
  249. except Exception as e:
  250. print_error("Exception while parsing class '{}': {}".format(name, e), state)
  251. state.sort_classes()
  252. for class_name, class_def in state.classes.items():
  253. state.current_class = class_name
  254. make_rst_class(class_def, state, args.dry_run, args.output)
  255. if state.errored:
  256. exit(1)
  257. def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, State, bool, str) -> None
  258. class_name = class_def.name
  259. if dry_run:
  260. f = open(os.devnull, "w")
  261. else:
  262. f = open(os.path.join(output_dir, "class_" + class_name.lower() + '.rst'), 'w', encoding='utf-8')
  263. # Warn contributors not to edit this file directly
  264. f.write(":github_url: hide\n\n")
  265. f.write(".. Generated automatically by doc/tools/makerst.py in Godot's source tree.\n")
  266. f.write(".. DO NOT EDIT THIS FILE, but the " + class_name + ".xml source instead.\n")
  267. f.write(".. The source is found in doc/classes or modules/<name>/doc_classes.\n\n")
  268. f.write(".. _class_" + class_name + ":\n\n")
  269. f.write(make_heading(class_name, '='))
  270. # Inheritance tree
  271. # Ascendants
  272. if class_def.inherits:
  273. inh = class_def.inherits.strip()
  274. f.write('**Inherits:** ')
  275. first = True
  276. while inh in state.classes:
  277. if not first:
  278. f.write(" **<** ")
  279. else:
  280. first = False
  281. f.write(make_type(inh, state))
  282. inode = state.classes[inh].inherits
  283. if inode:
  284. inh = inode.strip()
  285. else:
  286. break
  287. f.write("\n\n")
  288. # Descendents
  289. inherited = []
  290. for c in state.classes.values():
  291. if c.inherits and c.inherits.strip() == class_name:
  292. inherited.append(c.name)
  293. if len(inherited):
  294. f.write('**Inherited By:** ')
  295. for i, child in enumerate(inherited):
  296. if i > 0:
  297. f.write(", ")
  298. f.write(make_type(child, state))
  299. f.write("\n\n")
  300. # Category
  301. if class_def.category is not None:
  302. f.write('**Category:** ' + class_def.category.strip() + "\n\n")
  303. # Brief description
  304. f.write(make_heading('Brief Description', '-'))
  305. if class_def.brief_description is not None:
  306. f.write(rstize_text(class_def.brief_description.strip(), state) + "\n\n")
  307. # Properties overview
  308. if len(class_def.properties) > 0:
  309. f.write(make_heading('Properties', '-'))
  310. ml = [] # type: List[Tuple[str, str, str]]
  311. for property_def in class_def.properties.values():
  312. type_rst = property_def.type_name.to_rst(state)
  313. default = property_def.default_value
  314. if property_def.overridden:
  315. ml.append((type_rst, property_def.name, "**O:** " + default))
  316. else:
  317. ref = ":ref:`{0}<class_{1}_property_{0}>`".format(property_def.name, class_name)
  318. ml.append((type_rst, ref, default))
  319. format_table(f, ml, True)
  320. # Methods overview
  321. if len(class_def.methods) > 0:
  322. f.write(make_heading('Methods', '-'))
  323. ml = []
  324. for method_list in class_def.methods.values():
  325. for m in method_list:
  326. ml.append(make_method_signature(class_def, m, True, state))
  327. format_table(f, ml)
  328. # Theme properties
  329. if class_def.theme_items is not None and len(class_def.theme_items) > 0:
  330. f.write(make_heading('Theme Properties', '-'))
  331. pl = []
  332. for theme_item_list in class_def.theme_items.values():
  333. for theme_item in theme_item_list:
  334. pl.append((theme_item.type_name.to_rst(state), theme_item.name, theme_item.default_value))
  335. format_table(f, pl, True)
  336. # Signals
  337. if len(class_def.signals) > 0:
  338. f.write(make_heading('Signals', '-'))
  339. for signal in class_def.signals.values():
  340. #f.write(".. _class_{}_{}:\n\n".format(class_name, signal.name))
  341. f.write(".. _class_{}_signal_{}:\n\n".format(class_name, signal.name))
  342. _, signature = make_method_signature(class_def, signal, False, state)
  343. f.write("- {}\n\n".format(signature))
  344. if signal.description is None or signal.description.strip() == '':
  345. continue
  346. f.write(rstize_text(signal.description.strip(), state))
  347. f.write("\n\n")
  348. # Enums
  349. if len(class_def.enums) > 0:
  350. f.write(make_heading('Enumerations', '-'))
  351. for e in class_def.enums.values():
  352. f.write(".. _enum_{}_{}:\n\n".format(class_name, e.name))
  353. # Sphinx seems to divide the bullet list into individual <ul> tags if we weave the labels into it.
  354. # As such I'll put them all above the list. Won't be perfect but better than making the list visually broken.
  355. # As to why I'm not modifying the reference parser to directly link to the _enum label:
  356. # If somebody gets annoyed enough to fix it, all existing references will magically improve.
  357. for value in e.values.values():
  358. f.write(".. _class_{}_constant_{}:\n\n".format(class_name, value.name))
  359. f.write("enum **{}**:\n\n".format(e.name))
  360. for value in e.values.values():
  361. f.write("- **{}** = **{}**".format(value.name, value.value))
  362. if value.text is not None and value.text.strip() != '':
  363. f.write(' --- ' + rstize_text(value.text.strip(), state))
  364. f.write('\n\n')
  365. # Constants
  366. if len(class_def.constants) > 0:
  367. f.write(make_heading('Constants', '-'))
  368. # Sphinx seems to divide the bullet list into individual <ul> tags if we weave the labels into it.
  369. # As such I'll put them all above the list. Won't be perfect but better than making the list visually broken.
  370. for constant in class_def.constants.values():
  371. f.write(".. _class_{}_constant_{}:\n\n".format(class_name, constant.name))
  372. for constant in class_def.constants.values():
  373. f.write("- **{}** = **{}**".format(constant.name, constant.value))
  374. if constant.text is not None and constant.text.strip() != '':
  375. f.write(' --- ' + rstize_text(constant.text.strip(), state))
  376. f.write('\n\n')
  377. # Class description
  378. if class_def.description is not None and class_def.description.strip() != '':
  379. f.write(make_heading('Description', '-'))
  380. f.write(rstize_text(class_def.description.strip(), state) + "\n\n")
  381. # Online tutorials
  382. if len(class_def.tutorials) > 0:
  383. f.write(make_heading('Tutorials', '-'))
  384. for t in class_def.tutorials:
  385. link = t.strip()
  386. f.write("- " + make_url(link) + "\n\n")
  387. # Property descriptions
  388. if any(not p.overridden for p in class_def.properties.values()) > 0:
  389. f.write(make_heading('Property Descriptions', '-'))
  390. for property_def in class_def.properties.values():
  391. if property_def.overridden:
  392. continue
  393. #f.write(".. _class_{}_{}:\n\n".format(class_name, property_def.name))
  394. f.write(".. _class_{}_property_{}:\n\n".format(class_name, property_def.name))
  395. f.write('- {} **{}**\n\n'.format(property_def.type_name.to_rst(state), property_def.name))
  396. info = []
  397. if property_def.default_value is not None:
  398. info.append(("*Default*", property_def.default_value))
  399. if property_def.setter is not None and not property_def.setter.startswith("_"):
  400. info.append(("*Setter*", property_def.setter + '(value)'))
  401. if property_def.getter is not None and not property_def.getter.startswith("_"):
  402. info.append(('*Getter*', property_def.getter + '()'))
  403. if len(info) > 0:
  404. format_table(f, info)
  405. if property_def.text is not None and property_def.text.strip() != '':
  406. f.write(rstize_text(property_def.text.strip(), state))
  407. f.write('\n\n')
  408. # Method descriptions
  409. if len(class_def.methods) > 0:
  410. f.write(make_heading('Method Descriptions', '-'))
  411. for method_list in class_def.methods.values():
  412. for i, m in enumerate(method_list):
  413. if i == 0:
  414. #f.write(".. _class_{}_{}:\n\n".format(class_name, m.name))
  415. f.write(".. _class_{}_method_{}:\n\n".format(class_name, m.name))
  416. ret_type, signature = make_method_signature(class_def, m, False, state)
  417. f.write("- {} {}\n\n".format(ret_type, signature))
  418. if m.description is None or m.description.strip() == '':
  419. continue
  420. f.write(rstize_text(m.description.strip(), state))
  421. f.write("\n\n")
  422. def make_class_list(class_list, columns): # type: (List[str], int) -> None
  423. # This function is no longer used.
  424. f = open('class_list.rst', 'w', encoding='utf-8')
  425. col_max = len(class_list) // columns + 1
  426. print(('col max is ', col_max))
  427. fit_columns = [] # type: List[List[str]]
  428. for _ in range(0, columns):
  429. fit_columns.append([])
  430. indexers = [] # type List[str]
  431. last_initial = ''
  432. for idx, name in enumerate(class_list):
  433. col = idx // col_max
  434. if col >= columns:
  435. col = columns - 1
  436. fit_columns[col].append(name)
  437. idx += 1
  438. if name[:1] != last_initial:
  439. indexers.append(name)
  440. last_initial = name[:1]
  441. row_max = 0
  442. f.write("\n")
  443. for n in range(0, columns):
  444. if len(fit_columns[n]) > row_max:
  445. row_max = len(fit_columns[n])
  446. f.write("| ")
  447. for n in range(0, columns):
  448. f.write(" | |")
  449. f.write("\n")
  450. f.write("+")
  451. for n in range(0, columns):
  452. f.write("--+-------+")
  453. f.write("\n")
  454. for r in range(0, row_max):
  455. s = '+ '
  456. for c in range(0, columns):
  457. if r >= len(fit_columns[c]):
  458. continue
  459. classname = fit_columns[c][r]
  460. initial = classname[0]
  461. if classname in indexers:
  462. s += '**' + initial + '** | '
  463. else:
  464. s += ' | '
  465. s += '[' + classname + '](class_' + classname.lower() + ') | '
  466. s += '\n'
  467. f.write(s)
  468. for n in range(0, columns):
  469. f.write("--+-------+")
  470. f.write("\n")
  471. f.close()
  472. def rstize_text(text, state): # type: (str, State) -> str
  473. # Linebreak + tabs in the XML should become two line breaks unless in a "codeblock"
  474. pos = 0
  475. while True:
  476. pos = text.find('\n', pos)
  477. if pos == -1:
  478. break
  479. pre_text = text[:pos]
  480. indent_level = 0
  481. while text[pos + 1] == '\t':
  482. pos += 1
  483. indent_level += 1
  484. post_text = text[pos + 1:]
  485. # Handle codeblocks
  486. if post_text.startswith("[codeblock]"):
  487. end_pos = post_text.find("[/codeblock]")
  488. if end_pos == -1:
  489. print_error("[codeblock] without a closing tag, file: {}".format(state.current_class), state)
  490. return ""
  491. code_text = post_text[len("[codeblock]"):end_pos]
  492. post_text = post_text[end_pos:]
  493. # Remove extraneous tabs
  494. code_pos = 0
  495. while True:
  496. code_pos = code_text.find('\n', code_pos)
  497. if code_pos == -1:
  498. break
  499. to_skip = 0
  500. while code_pos + to_skip + 1 < len(code_text) and code_text[code_pos + to_skip + 1] == '\t':
  501. to_skip += 1
  502. if to_skip > indent_level:
  503. print_error("Four spaces should be used for indentation within [codeblock], file: {}".format(state.current_class), state)
  504. if len(code_text[code_pos + to_skip + 1:]) == 0:
  505. code_text = code_text[:code_pos] + "\n"
  506. code_pos += 1
  507. else:
  508. code_text = code_text[:code_pos] + "\n " + code_text[code_pos + to_skip + 1:]
  509. code_pos += 5 - to_skip
  510. text = pre_text + "\n[codeblock]" + code_text + post_text
  511. pos += len("\n[codeblock]" + code_text)
  512. # Handle normal text
  513. else:
  514. text = pre_text + "\n\n" + post_text
  515. pos += 2
  516. next_brac_pos = text.find('[')
  517. # Escape \ character, otherwise it ends up as an escape character in rst
  518. pos = 0
  519. while True:
  520. pos = text.find('\\', pos, next_brac_pos)
  521. if pos == -1:
  522. break
  523. text = text[:pos] + "\\\\" + text[pos + 1:]
  524. pos += 2
  525. # Escape * character to avoid interpreting it as emphasis
  526. pos = 0
  527. while True:
  528. pos = text.find('*', pos, next_brac_pos)
  529. if pos == -1:
  530. break
  531. text = text[:pos] + "\*" + text[pos + 1:]
  532. pos += 2
  533. # Escape _ character at the end of a word to avoid interpreting it as an inline hyperlink
  534. pos = 0
  535. while True:
  536. pos = text.find('_', pos, next_brac_pos)
  537. if pos == -1:
  538. break
  539. if not text[pos + 1].isalnum(): # don't escape within a snake_case word
  540. text = text[:pos] + "\_" + text[pos + 1:]
  541. pos += 2
  542. else:
  543. pos += 1
  544. # Handle [tags]
  545. inside_code = False
  546. inside_url = False
  547. url_has_name = False
  548. url_link = ""
  549. pos = 0
  550. tag_depth = 0
  551. previous_pos = 0
  552. while True:
  553. pos = text.find('[', pos)
  554. if inside_url and (pos > previous_pos):
  555. url_has_name = True
  556. if pos == -1:
  557. break
  558. endq_pos = text.find(']', pos + 1)
  559. if endq_pos == -1:
  560. break
  561. pre_text = text[:pos]
  562. post_text = text[endq_pos + 1:]
  563. tag_text = text[pos + 1:endq_pos]
  564. escape_post = False
  565. if tag_text in state.classes:
  566. if tag_text == state.current_class:
  567. # We don't want references to the same class
  568. tag_text = '``{}``'.format(tag_text)
  569. else:
  570. tag_text = make_type(tag_text, state)
  571. escape_post = True
  572. else: # command
  573. cmd = tag_text
  574. space_pos = tag_text.find(' ')
  575. if cmd == '/codeblock':
  576. tag_text = ''
  577. tag_depth -= 1
  578. inside_code = False
  579. # Strip newline if the tag was alone on one
  580. if pre_text[-1] == '\n':
  581. pre_text = pre_text[:-1]
  582. elif cmd == '/code':
  583. tag_text = '``'
  584. tag_depth -= 1
  585. inside_code = False
  586. escape_post = True
  587. elif inside_code:
  588. tag_text = '[' + tag_text + ']'
  589. elif cmd.find('html') == 0:
  590. param = tag_text[space_pos + 1:]
  591. tag_text = param
  592. elif cmd.startswith('method') or cmd.startswith('member') or cmd.startswith('signal') or cmd.startswith('constant'):
  593. param = tag_text[space_pos + 1:]
  594. if param.find('.') != -1:
  595. ss = param.split('.')
  596. if len(ss) > 2:
  597. print_error("Bad reference: '{}', file: {}".format(param, state.current_class), state)
  598. class_param, method_param = ss
  599. else:
  600. class_param = state.current_class
  601. method_param = param
  602. ref_type = ""
  603. if class_param in state.classes:
  604. class_def = state.classes[class_param]
  605. if cmd.startswith("method"):
  606. if method_param not in class_def.methods:
  607. print_error("Unresolved method '{}', file: {}".format(param, state.current_class), state)
  608. ref_type = "_method"
  609. elif cmd.startswith("member"):
  610. if method_param not in class_def.properties:
  611. print_error("Unresolved member '{}', file: {}".format(param, state.current_class), state)
  612. ref_type = "_property"
  613. elif cmd.startswith("signal"):
  614. if method_param not in class_def.signals:
  615. print_error("Unresolved signal '{}', file: {}".format(param, state.current_class), state)
  616. ref_type = "_signal"
  617. elif cmd.startswith("constant"):
  618. found = False
  619. # Search in the current class
  620. search_class_defs = [class_def]
  621. if param.find('.') == -1:
  622. # Also search in @GlobalScope as a last resort if no class was specified
  623. search_class_defs.append(state.classes["@GlobalScope"])
  624. for search_class_def in search_class_defs:
  625. if method_param in search_class_def.constants:
  626. class_param = search_class_def.name
  627. found = True
  628. else:
  629. for enum in search_class_def.enums.values():
  630. if method_param in enum.values:
  631. class_param = search_class_def.name
  632. found = True
  633. break
  634. if not found:
  635. print_error("Unresolved constant '{}', file: {}".format(param, state.current_class), state)
  636. ref_type = "_constant"
  637. else:
  638. print_error("Unresolved type reference '{}' in method reference '{}', file: {}".format(class_param, param, state.current_class), state)
  639. repl_text = method_param
  640. if class_param != state.current_class:
  641. repl_text = "{}.{}".format(class_param, method_param)
  642. tag_text = ':ref:`{}<class_{}{}_{}>`'.format(repl_text, class_param, ref_type, method_param)
  643. escape_post = True
  644. elif cmd.find('image=') == 0:
  645. tag_text = "" # '![](' + cmd[6:] + ')'
  646. elif cmd.find('url=') == 0:
  647. url_link = cmd[4:]
  648. tag_text = '`'
  649. tag_depth += 1
  650. inside_url = True
  651. url_has_name = False
  652. elif cmd == '/url':
  653. tag_text = ('' if url_has_name else url_link) + " <" + url_link + ">`_"
  654. tag_depth -= 1
  655. escape_post = True
  656. inside_url = False
  657. url_has_name = False
  658. elif cmd == 'center':
  659. tag_depth += 1
  660. tag_text = ''
  661. elif cmd == '/center':
  662. tag_depth -= 1
  663. tag_text = ''
  664. elif cmd == 'codeblock':
  665. tag_depth += 1
  666. tag_text = '\n::\n'
  667. inside_code = True
  668. elif cmd == 'br':
  669. # Make a new paragraph instead of a linebreak, rst is not so linebreak friendly
  670. tag_text = '\n\n'
  671. # Strip potential leading spaces
  672. while post_text[0] == ' ':
  673. post_text = post_text[1:]
  674. elif cmd == 'i' or cmd == '/i':
  675. if cmd == "/i":
  676. tag_depth -= 1
  677. else:
  678. tag_depth += 1
  679. tag_text = '*'
  680. elif cmd == 'b' or cmd == '/b':
  681. if cmd == "/b":
  682. tag_depth -= 1
  683. else:
  684. tag_depth += 1
  685. tag_text = '**'
  686. elif cmd == 'u' or cmd == '/u':
  687. if cmd == "/u":
  688. tag_depth -= 1
  689. else:
  690. tag_depth += 1
  691. tag_text = ''
  692. elif cmd == 'code':
  693. tag_text = '``'
  694. tag_depth += 1
  695. inside_code = True
  696. elif cmd.startswith('enum '):
  697. tag_text = make_enum(cmd[5:], state)
  698. else:
  699. tag_text = make_type(tag_text, state)
  700. escape_post = True
  701. # Properly escape things like `[Node]s`
  702. if escape_post and post_text and (post_text[0].isalnum() or post_text[0] == "("): # not punctuation, escape
  703. post_text = '\ ' + post_text
  704. next_brac_pos = post_text.find('[', 0)
  705. iter_pos = 0
  706. while not inside_code:
  707. iter_pos = post_text.find('*', iter_pos, next_brac_pos)
  708. if iter_pos == -1:
  709. break
  710. post_text = post_text[:iter_pos] + "\*" + post_text[iter_pos + 1:]
  711. iter_pos += 2
  712. iter_pos = 0
  713. while not inside_code:
  714. iter_pos = post_text.find('_', iter_pos, next_brac_pos)
  715. if iter_pos == -1:
  716. break
  717. if not post_text[iter_pos + 1].isalnum(): # don't escape within a snake_case word
  718. post_text = post_text[:iter_pos] + "\_" + post_text[iter_pos + 1:]
  719. iter_pos += 2
  720. else:
  721. iter_pos += 1
  722. text = pre_text + tag_text + post_text
  723. pos = len(pre_text) + len(tag_text)
  724. previous_pos = pos
  725. if tag_depth > 0:
  726. print_error("Tag depth mismatch: too many/little open/close tags, file: {}".format(state.current_class), state)
  727. return text
  728. def format_table(f, data, remove_empty_columns=False): # type: (TextIO, Iterable[Tuple[str, ...]]) -> None
  729. if len(data) == 0:
  730. return
  731. column_sizes = [0] * len(data[0])
  732. for row in data:
  733. for i, text in enumerate(row):
  734. text_length = len(text or '')
  735. if text_length > column_sizes[i]:
  736. column_sizes[i] = text_length
  737. sep = ""
  738. for size in column_sizes:
  739. if size == 0 and remove_empty_columns:
  740. continue
  741. sep += "+" + "-" * (size + 2)
  742. sep += "+\n"
  743. f.write(sep)
  744. for row in data:
  745. row_text = "|"
  746. for i, text in enumerate(row):
  747. if column_sizes[i] == 0 and remove_empty_columns:
  748. continue
  749. row_text += " " + (text or '').ljust(column_sizes[i]) + " |"
  750. row_text += "\n"
  751. f.write(row_text)
  752. f.write(sep)
  753. f.write('\n')
  754. def make_type(t, state): # type: (str, State) -> str
  755. if t in state.classes:
  756. return ':ref:`{0}<class_{0}>`'.format(t)
  757. print_error("Unresolved type '{}', file: {}".format(t, state.current_class), state)
  758. return t
  759. def make_enum(t, state): # type: (str, State) -> str
  760. p = t.find(".")
  761. if p >= 0:
  762. c = t[0:p]
  763. e = t[p + 1:]
  764. # Variant enums live in GlobalScope but still use periods.
  765. if c == "Variant":
  766. c = "@GlobalScope"
  767. e = "Variant." + e
  768. else:
  769. c = state.current_class
  770. e = t
  771. if c in state.classes and e not in state.classes[c].enums:
  772. c = "@GlobalScope"
  773. if not c in state.classes and c.startswith("_"):
  774. c = c[1:] # Remove the underscore prefix
  775. if c in state.classes and e in state.classes[c].enums:
  776. return ":ref:`{0}<enum_{1}_{0}>`".format(e, c)
  777. print_error("Unresolved enum '{}', file: {}".format(t, state.current_class), state)
  778. return t
  779. def make_method_signature(class_def, method_def, make_ref, state): # type: (ClassDef, Union[MethodDef, SignalDef], bool, State) -> Tuple[str, str]
  780. ret_type = " "
  781. ref_type = "signal"
  782. if isinstance(method_def, MethodDef):
  783. ret_type = method_def.return_type.to_rst(state)
  784. ref_type = "method"
  785. out = ""
  786. if make_ref:
  787. out += ":ref:`{0}<class_{1}_{2}_{0}>` ".format(method_def.name, class_def.name, ref_type)
  788. else:
  789. out += "**{}** ".format(method_def.name)
  790. out += '**(**'
  791. for i, arg in enumerate(method_def.parameters):
  792. if i > 0:
  793. out += ', '
  794. else:
  795. out += ' '
  796. out += "{} {}".format(arg.type_name.to_rst(state), arg.name)
  797. if arg.default_value is not None:
  798. out += '=' + arg.default_value
  799. if isinstance(method_def, MethodDef) and method_def.qualifiers is not None and 'vararg' in method_def.qualifiers:
  800. if len(method_def.parameters) > 0:
  801. out += ', ...'
  802. else:
  803. out += ' ...'
  804. out += ' **)**'
  805. if isinstance(method_def, MethodDef) and method_def.qualifiers is not None:
  806. out += ' ' + method_def.qualifiers
  807. return ret_type, out
  808. def make_heading(title, underline): # type: (str, str) -> str
  809. return title + '\n' + (underline * len(title)) + "\n\n"
  810. def make_url(link): # type: (str) -> str
  811. match = GODOT_DOCS_PATTERN.search(link)
  812. if match:
  813. groups = match.groups()
  814. if match.lastindex == 2:
  815. # Doc reference with fragment identifier: emit direct link to section with reference to page, for example:
  816. # `#calling-javascript-from-script in Exporting For Web`
  817. return "`" + groups[1] + " <../" + groups[0] + ".html" + groups[1] + ">`_ in :doc:`../" + groups[0] + "`"
  818. # Commented out alternative: Instead just emit:
  819. # `Subsection in Exporting For Web`
  820. # return "`Subsection <../" + groups[0] + ".html" + groups[1] + ">`__ in :doc:`../" + groups[0] + "`"
  821. elif match.lastindex == 1:
  822. # Doc reference, for example:
  823. # `Math`
  824. return ":doc:`../" + groups[0] + "`"
  825. else:
  826. # External link, for example:
  827. # `http://enet.bespin.org/usergroup0.html`
  828. return "`" + link + " <" + link + ">`_"
  829. if __name__ == '__main__':
  830. main()