Mercurial Repositories > eric / file comparison

comparison: DocumentationTools/ModuleDocumentor.py

DocumentationTools/ModuleDocumentor.py

branch
Py2 comp.
changeset 3057
10516539f238
parent 2525
8b507a9a2d40
parent 2991
226481ff40d1
child 3058
0a02c433f52d
equal deleted inserted replaced
3056:9986ec0e559a 3057:10516539f238
50 50
51 class TagError(Exception): 51 class TagError(Exception):
52 """ 52 """
53 Exception class raised, if an invalid documentation tag was found. 53 Exception class raised, if an invalid documentation tag was found.
54 """ 54 """
55 pass
55 56
56 57
57 class ModuleDocument(object): 58 class ModuleDocument(object):
58 """ 59 """
59 Class implementing the builtin documentation generator. 60 Class implementing the builtin documentation generator.
78 self.footerTemplate = TemplatesListsStyleCSS.footerTemplate 79 self.footerTemplate = TemplatesListsStyleCSS.footerTemplate
79 self.moduleTemplate = TemplatesListsStyleCSS.moduleTemplate 80 self.moduleTemplate = TemplatesListsStyleCSS.moduleTemplate
80 self.rbFileTemplate = TemplatesListsStyleCSS.rbFileTemplate 81 self.rbFileTemplate = TemplatesListsStyleCSS.rbFileTemplate
81 self.classTemplate = TemplatesListsStyleCSS.classTemplate 82 self.classTemplate = TemplatesListsStyleCSS.classTemplate
82 self.methodTemplate = TemplatesListsStyleCSS.methodTemplate 83 self.methodTemplate = TemplatesListsStyleCSS.methodTemplate
83 self.constructorTemplate = TemplatesListsStyleCSS.constructorTemplate 84 self.constructorTemplate = \
85 TemplatesListsStyleCSS.constructorTemplate
84 self.rbModuleTemplate = TemplatesListsStyleCSS.rbModuleTemplate 86 self.rbModuleTemplate = TemplatesListsStyleCSS.rbModuleTemplate
85 self.rbModulesClassTemplate = TemplatesListsStyleCSS.rbModulesClassTemplate 87 self.rbModulesClassTemplate = \
88 TemplatesListsStyleCSS.rbModulesClassTemplate
86 self.functionTemplate = TemplatesListsStyleCSS.functionTemplate 89 self.functionTemplate = TemplatesListsStyleCSS.functionTemplate
87 self.listTemplate = TemplatesListsStyleCSS.listTemplate 90 self.listTemplate = TemplatesListsStyleCSS.listTemplate
88 self.listEntryTemplate = TemplatesListsStyleCSS.listEntryTemplate 91 self.listEntryTemplate = TemplatesListsStyleCSS.listEntryTemplate
89 self.listEntryNoneTemplate = TemplatesListsStyleCSS.listEntryNoneTemplate 92 self.listEntryNoneTemplate = \
93 TemplatesListsStyleCSS.listEntryNoneTemplate
90 self.listEntryDeprecatedTemplate = \ 94 self.listEntryDeprecatedTemplate = \
91 TemplatesListsStyleCSS.listEntryDeprecatedTemplate 95 TemplatesListsStyleCSS.listEntryDeprecatedTemplate
92 self.listEntrySimpleTemplate = TemplatesListsStyleCSS.listEntrySimpleTemplate 96 self.listEntrySimpleTemplate = \
97 TemplatesListsStyleCSS.listEntrySimpleTemplate
93 self.paragraphTemplate = TemplatesListsStyleCSS.paragraphTemplate 98 self.paragraphTemplate = TemplatesListsStyleCSS.paragraphTemplate
94 self.parametersListTemplate = TemplatesListsStyleCSS.parametersListTemplate 99 self.parametersListTemplate = \
100 TemplatesListsStyleCSS.parametersListTemplate
95 self.parametersListEntryTemplate = \ 101 self.parametersListEntryTemplate = \
96 TemplatesListsStyleCSS.parametersListEntryTemplate 102 TemplatesListsStyleCSS.parametersListEntryTemplate
97 self.returnsTemplate = TemplatesListsStyleCSS.returnsTemplate 103 self.returnsTemplate = TemplatesListsStyleCSS.returnsTemplate
98 self.exceptionsListTemplate = TemplatesListsStyleCSS.exceptionsListTemplate 104 self.exceptionsListTemplate = \
105 TemplatesListsStyleCSS.exceptionsListTemplate
99 self.exceptionsListEntryTemplate = \ 106 self.exceptionsListEntryTemplate = \
100 TemplatesListsStyleCSS.exceptionsListEntryTemplate 107 TemplatesListsStyleCSS.exceptionsListEntryTemplate
101 self.signalsListTemplate = TemplatesListsStyleCSS.signalsListTemplate 108 self.signalsListTemplate = \
109 TemplatesListsStyleCSS.signalsListTemplate
102 self.signalsListEntryTemplate = \ 110 self.signalsListEntryTemplate = \
103 TemplatesListsStyleCSS.signalsListEntryTemplate 111 TemplatesListsStyleCSS.signalsListEntryTemplate
104 self.eventsListTemplate = TemplatesListsStyleCSS.eventsListTemplate 112 self.eventsListTemplate = TemplatesListsStyleCSS.eventsListTemplate
105 self.eventsListEntryTemplate = TemplatesListsStyleCSS.eventsListEntryTemplate 113 self.eventsListEntryTemplate = \
114 TemplatesListsStyleCSS.eventsListEntryTemplate
106 self.deprecatedTemplate = TemplatesListsStyleCSS.deprecatedTemplate 115 self.deprecatedTemplate = TemplatesListsStyleCSS.deprecatedTemplate
107 self.authorInfoTemplate = TemplatesListsStyleCSS.authorInfoTemplate 116 self.authorInfoTemplate = TemplatesListsStyleCSS.authorInfoTemplate
108 self.seeListTemplate = TemplatesListsStyleCSS.seeListTemplate 117 self.seeListTemplate = TemplatesListsStyleCSS.seeListTemplate
109 self.seeListEntryTemplate = TemplatesListsStyleCSS.seeListEntryTemplate 118 self.seeListEntryTemplate = \
119 TemplatesListsStyleCSS.seeListEntryTemplate
110 self.seeLinkTemplate = TemplatesListsStyleCSS.seeLinkTemplate 120 self.seeLinkTemplate = TemplatesListsStyleCSS.seeLinkTemplate
111 self.sinceInfoTemplate = TemplatesListsStyleCSS.sinceInfoTemplate 121 self.sinceInfoTemplate = TemplatesListsStyleCSS.sinceInfoTemplate
112 else: 122 else:
113 from . import TemplatesListsStyle 123 from . import TemplatesListsStyle
114 self.headerTemplate = TemplatesListsStyle.headerTemplate.format(**colors) 124 self.headerTemplate = \
115 self.footerTemplate = TemplatesListsStyle.footerTemplate.format(**colors) 125 TemplatesListsStyle.headerTemplate.format(**colors)
116 self.moduleTemplate = TemplatesListsStyle.moduleTemplate.format(**colors) 126 self.footerTemplate = \
117 self.rbFileTemplate = TemplatesListsStyle.rbFileTemplate.format(**colors) 127 TemplatesListsStyle.footerTemplate.format(**colors)
118 self.classTemplate = TemplatesListsStyle.classTemplate.format(**colors) 128 self.moduleTemplate = \
119 self.methodTemplate = TemplatesListsStyle.methodTemplate.format(**colors) 129 TemplatesListsStyle.moduleTemplate.format(**colors)
130 self.rbFileTemplate = \
131 TemplatesListsStyle.rbFileTemplate.format(**colors)
132 self.classTemplate = \
133 TemplatesListsStyle.classTemplate.format(**colors)
134 self.methodTemplate = \
135 TemplatesListsStyle.methodTemplate.format(**colors)
120 self.constructorTemplate = \ 136 self.constructorTemplate = \
121 TemplatesListsStyle.constructorTemplate.format(**colors) 137 TemplatesListsStyle.constructorTemplate.format(**colors)
122 self.rbModuleTemplate = TemplatesListsStyle.rbModuleTemplate.format(**colors) 138 self.rbModuleTemplate = \
139 TemplatesListsStyle.rbModuleTemplate.format(**colors)
123 self.rbModulesClassTemplate = \ 140 self.rbModulesClassTemplate = \
124 TemplatesListsStyle.rbModulesClassTemplate.format(**colors) 141 TemplatesListsStyle.rbModulesClassTemplate.format(**colors)
125 self.functionTemplate = TemplatesListsStyle.functionTemplate.format(**colors) 142 self.functionTemplate = \
126 self.listTemplate = TemplatesListsStyle.listTemplate.format(**colors) 143 TemplatesListsStyle.functionTemplate.format(**colors)
144 self.listTemplate = \
145 TemplatesListsStyle.listTemplate.format(**colors)
127 self.listEntryTemplate = \ 146 self.listEntryTemplate = \
128 TemplatesListsStyle.listEntryTemplate.format(**colors) 147 TemplatesListsStyle.listEntryTemplate.format(**colors)
129 self.listEntryNoneTemplate = \ 148 self.listEntryNoneTemplate = \
130 TemplatesListsStyle.listEntryNoneTemplate.format(**colors) 149 TemplatesListsStyle.listEntryNoneTemplate.format(**colors)
131 self.listEntryDeprecatedTemplate = \ 150 self.listEntryDeprecatedTemplate = \
132 TemplatesListsStyle.listEntryDeprecatedTemplate.format(**colors) 151 TemplatesListsStyle.listEntryDeprecatedTemplate.format(
152 **colors)
133 self.listEntrySimpleTemplate = \ 153 self.listEntrySimpleTemplate = \
134 TemplatesListsStyle.listEntrySimpleTemplate.format(**colors) 154 TemplatesListsStyle.listEntrySimpleTemplate.format(**colors)
135 self.paragraphTemplate = \ 155 self.paragraphTemplate = \
136 TemplatesListsStyle.paragraphTemplate.format(**colors) 156 TemplatesListsStyle.paragraphTemplate.format(**colors)
137 self.parametersListTemplate = \ 157 self.parametersListTemplate = \
138 TemplatesListsStyle.parametersListTemplate.format(**colors) 158 TemplatesListsStyle.parametersListTemplate.format(**colors)
139 self.parametersListEntryTemplate = \ 159 self.parametersListEntryTemplate = \
140 TemplatesListsStyle.parametersListEntryTemplate.format(**colors) 160 TemplatesListsStyle.parametersListEntryTemplate.format(
141 self.returnsTemplate = TemplatesListsStyle.returnsTemplate.format(**colors) 161 **colors)
162 self.returnsTemplate = \
163 TemplatesListsStyle.returnsTemplate.format(**colors)
142 self.exceptionsListTemplate = \ 164 self.exceptionsListTemplate = \
143 TemplatesListsStyle.exceptionsListTemplate.format(**colors) 165 TemplatesListsStyle.exceptionsListTemplate.format(**colors)
144 self.exceptionsListEntryTemplate = \ 166 self.exceptionsListEntryTemplate = \
145 TemplatesListsStyle.exceptionsListEntryTemplate.format(**colors) 167 TemplatesListsStyle.exceptionsListEntryTemplate.format(
168 **colors)
146 self.signalsListTemplate = \ 169 self.signalsListTemplate = \
147 TemplatesListsStyle.signalsListTemplate.format(**colors) 170 TemplatesListsStyle.signalsListTemplate.format(**colors)
148 self.signalsListEntryTemplate = \ 171 self.signalsListEntryTemplate = \
149 TemplatesListsStyle.signalsListEntryTemplate.format(**colors) 172 TemplatesListsStyle.signalsListEntryTemplate.format(**colors)
150 self.eventsListTemplate = \ 173 self.eventsListTemplate = \
153 TemplatesListsStyle.eventsListEntryTemplate.format(**colors) 176 TemplatesListsStyle.eventsListEntryTemplate.format(**colors)
154 self.deprecatedTemplate = \ 177 self.deprecatedTemplate = \
155 TemplatesListsStyle.deprecatedTemplate.format(**colors) 178 TemplatesListsStyle.deprecatedTemplate.format(**colors)
156 self.authorInfoTemplate = \ 179 self.authorInfoTemplate = \
157 TemplatesListsStyle.authorInfoTemplate.format(**colors) 180 TemplatesListsStyle.authorInfoTemplate.format(**colors)
158 self.seeListTemplate = TemplatesListsStyle.seeListTemplate.format(**colors) 181 self.seeListTemplate = \
182 TemplatesListsStyle.seeListTemplate.format(**colors)
159 self.seeListEntryTemplate = \ 183 self.seeListEntryTemplate = \
160 TemplatesListsStyle.seeListEntryTemplate.format(**colors) 184 TemplatesListsStyle.seeListEntryTemplate.format(**colors)
161 self.seeLinkTemplate = TemplatesListsStyle.seeLinkTemplate.format(**colors) 185 self.seeLinkTemplate = \
186 TemplatesListsStyle.seeLinkTemplate.format(**colors)
162 self.sinceInfoTemplate = \ 187 self.sinceInfoTemplate = \
163 TemplatesListsStyle.sinceInfoTemplate.format(**colors) 188 TemplatesListsStyle.sinceInfoTemplate.format(**colors)
164 189
165 self.keywords = [] # list of tuples containing the name (string) and 190 self.keywords = []
166 # the ref (string). The ref is without the filename part. 191 # list of tuples containing the name (string) and
192 # the ref (string). The ref is without the filename part.
167 self.generated = False 193 self.generated = False
168 194
169 def isEmpty(self): 195 def isEmpty(self):
170 """ 196 """
171 Public method to determine, if the module contains any classes or functions. 197 Public method to determine, if the module contains any classes or
198 functions.
172 199
173 @return Flag indicating an empty module (i.e. __init__.py without 200 @return Flag indicating an empty module (i.e. __init__.py without
174 any contents) 201 any contents)
175 """ 202 """
176 return self.empty 203 return self.empty
245 'GlobalsList': globalsList, 272 'GlobalsList': globalsList,
246 'ClassList': classList, 273 'ClassList': classList,
247 'FunctionList': functionList, 274 'FunctionList': functionList,
248 }) 275 })
249 except TagError as e: 276 except TagError as e:
250 sys.stderr.write("Error in tags of description of module {0}.\n".format( 277 sys.stderr.write(
278 "Error in tags of description of module {0}.\n".format(
251 self.module.name)) 279 self.module.name))
252 sys.stderr.write("{0}\n".format(e)) 280 sys.stderr.write("{0}\n".format(e))
253 return "" 281 return ""
254 282
255 classesSection = self.__genClassesSection() 283 classesSection = self.__genClassesSection()
273 lst = [] 301 lst = []
274 for name in names: 302 for name in names:
275 lst.append(self.listEntryTemplate.format(**{ \ 303 lst.append(self.listEntryTemplate.format(**{ \
276 'Link': "{0}".format(name), 304 'Link': "{0}".format(name),
277 'Name': dict[name].name, 305 'Name': dict[name].name,
278 'Description': self.__getShortDescription(dict[name].description), 306 'Description':
279 'Deprecated': self.__checkDeprecated(dict[name].description) and \ 307 self.__getShortDescription(dict[name].description),
308 'Deprecated':
309 self.__checkDeprecated(dict[name].description) and \
280 self.listEntryDeprecatedTemplate or "", 310 self.listEntryDeprecatedTemplate or "",
281 })) 311 }))
282 if kwSuffix: 312 if kwSuffix:
283 n = "{0} ({1})".format(name, kwSuffix) 313 n = "{0} ({1})".format(name, kwSuffix)
284 else: 314 else:
311 'Entries': s, 341 'Entries': s,
312 }) 342 })
313 343
314 def __genClassListSection(self): 344 def __genClassListSection(self):
315 """ 345 """
316 Private method to generate the section listing all classes of the module. 346 Private method to generate the section listing all classes of the
347 module.
317 348
318 @return The classes list section. (string) 349 @return The classes list section. (string)
319 """ 350 """
320 names = sorted(list(self.module.classes.keys())) 351 names = sorted(list(self.module.classes.keys()))
321 if names: 352 if names:
344 'Entries': s, 375 'Entries': s,
345 }) 376 })
346 377
347 def __genFunctionListSection(self): 378 def __genFunctionListSection(self):
348 """ 379 """
349 Private method to generate the section listing all functions of the module. 380 Private method to generate the section listing all functions of the
381 module.
350 382
351 @return The functions list section. (string) 383 @return The functions list section. (string)
352 """ 384 """
353 names = sorted(list(self.module.functions.keys())) 385 names = sorted(list(self.module.functions.keys()))
354 if names: 386 if names:
360 'Entries': s, 392 'Entries': s,
361 }) 393 })
362 394
363 def __genClassesSection(self): 395 def __genClassesSection(self):
364 """ 396 """
365 Private method to generate the document section with details about classes. 397 Private method to generate the document section with details about
398 classes.
366 399
367 @return The classes details section. (string) 400 @return The classes details section. (string)
368 """ 401 """
369 classNames = sorted(list(self.module.classes.keys())) 402 classNames = sorted(list(self.module.classes.keys()))
370 classes = [] 403 classes = []
387 try: 420 try:
388 clsBody = self.classTemplate.format(**{ \ 421 clsBody = self.classTemplate.format(**{ \
389 'Anchor': className, 422 'Anchor': className,
390 'Class': _class.name, 423 'Class': _class.name,
391 'ClassSuper': supers, 424 'ClassSuper': supers,
392 'ClassDescription': self.__formatDescription(_class.description), 425 'ClassDescription':
426 self.__formatDescription(_class.description),
393 'GlobalsList': globalsList, 427 'GlobalsList': globalsList,
394 'ClassMethodList': classMethList, 428 'ClassMethodList': classMethList,
395 'MethodList': methList, 429 'MethodList': methList,
396 'StaticMethodList': staticMethList, 430 'StaticMethodList': staticMethList,
397 'MethodDetails': classMethBodies + methBodies + staticMethBodies, 431 'MethodDetails':
432 classMethBodies + methBodies + staticMethBodies,
398 }) 433 })
399 except TagError as e: 434 except TagError as e:
400 sys.stderr.write("Error in tags of description of class {0}.\n".format( 435 sys.stderr.write(
436 "Error in tags of description of class {0}.\n".format(
401 className)) 437 className))
402 sys.stderr.write("{0}\n".format(e)) 438 sys.stderr.write("{0}\n".format(e))
403 clsBody = "" 439 clsBody = ""
404 440
405 classes.append(clsBody) 441 classes.append(clsBody)
413 449
414 @param names names to appear in the list (list of strings) 450 @param names names to appear in the list (list of strings)
415 @param dict dictionary containing all relevant information 451 @param dict dictionary containing all relevant information
416 @param className class name containing the names 452 @param className class name containing the names
417 @param clsName visible class name containing the names 453 @param clsName visible class name containing the names
418 @param includeInit flag indicating to include the __init__ method (boolean) 454 @param includeInit flag indicating to include the __init__ method
455 (boolean)
419 @return methods list section (string) 456 @return methods list section (string)
420 """ 457 """
421 lst = [] 458 lst = []
422 if includeInit: 459 if includeInit:
423 try: 460 try:
428 dict['__init__'].description), 465 dict['__init__'].description),
429 'Deprecated': self.__checkDeprecated( 466 'Deprecated': self.__checkDeprecated(
430 dict['__init__'].description) and \ 467 dict['__init__'].description) and \
431 self.listEntryDeprecatedTemplate or "", 468 self.listEntryDeprecatedTemplate or "",
432 })) 469 }))
433 self.keywords.append(("{0} (Constructor)".format(className), 470 self.keywords.append(
434 "#{0}.{1}".format(className, '__init__'))) 471 ("{0} (Constructor)".format(className),
472 "#{0}.{1}".format(className, '__init__')))
435 except KeyError: 473 except KeyError:
436 pass 474 pass
437 475
438 for name in names: 476 for name in names:
439 lst.append(self.listEntryTemplate.format(**{ \ 477 lst.append(self.listEntryTemplate.format(**{ \
440 'Link': "{0}.{1}".format(className, name), 478 'Link': "{0}.{1}".format(className, name),
441 'Name': dict[name].name, 479 'Name': dict[name].name,
442 'Description': self.__getShortDescription(dict[name].description), 480 'Description':
443 'Deprecated': self.__checkDeprecated(dict[name].description) and \ 481 self.__getShortDescription(dict[name].description),
444 self.listEntryDeprecatedTemplate or "", 482 'Deprecated':
483 self.__checkDeprecated(dict[name].description) and \
484 self.listEntryDeprecatedTemplate or "",
445 })) 485 }))
446 self.keywords.append(("{0}.{1}".format(className, name), 486 self.keywords.append(("{0}.{1}".format(className, name),
447 "#{0}.{1}".format(className, name))) 487 "#{0}.{1}".format(className, name)))
448 return ''.join(lst) 488 return ''.join(lst)
449 489
466 methBody = self.constructorTemplate.format(**{ \ 506 methBody = self.constructorTemplate.format(**{ \
467 'Anchor': className, 507 'Anchor': className,
468 'Class': obj.name, 508 'Class': obj.name,
469 'Method': '__init__', 509 'Method': '__init__',
470 'MethodDescription': \ 510 'MethodDescription': \
471 self.__formatDescription(obj.methods['__init__'].description), 511 self.__formatDescription(
472 'Params': ', '.join(obj.methods['__init__'].parameters[1:]), 512 obj.methods['__init__'].description),
513 'Params':
514 ', '.join(obj.methods['__init__'].parameters[1:]),
473 }) 515 })
474 except TagError as e: 516 except TagError as e:
475 sys.stderr.write( 517 sys.stderr.write(
476 "Error in tags of description of method {0}.{1}.\n".format( 518 "Error in tags of description of method {0}.{1}.\n".format(
477 className, '__init__')) 519 className, '__init__'))
490 methBody = self.methodTemplate.format(**{ \ 532 methBody = self.methodTemplate.format(**{ \
491 'Anchor': className, 533 'Anchor': className,
492 'Class': obj.name, 534 'Class': obj.name,
493 'Method': obj.methods[method].name, 535 'Method': obj.methods[method].name,
494 'MethodClassifier': methodClassifier, 536 'MethodClassifier': methodClassifier,
495 'MethodDescription': \ 537 'MethodDescription':
496 self.__formatDescription(obj.methods[method].description), 538 self.__formatDescription(
539 obj.methods[method].description),
497 'Params': ', '.join(obj.methods[method].parameters[1:]), 540 'Params': ', '.join(obj.methods[method].parameters[1:]),
498 }) 541 })
499 except TagError as e: 542 except TagError as e:
500 sys.stderr.write( 543 sys.stderr.write(
501 "Error in tags of description of method {0}.{1}.\n".format( 544 "Error in tags of description of method {0}.{1}.\n".format(
502 className, method)) 545 className, method))
503 sys.stderr.write("{0}\n".format(e)) 546 sys.stderr.write("{0}\n".format(e))
504 methBody = "" 547 methBody = ""
505 methBodies.append(methBody) 548 methBodies.append(methBody)
506 549
507 methList = self.__genMethodsListSection(methods, obj.methods, className, 550 methList = self.__genMethodsListSection(methods, obj.methods,
508 obj.name, includeInit=filter == Function.General) 551 className, obj.name, includeInit=filter == Function.General)
509 552
510 if not methList: 553 if not methList:
511 methList = self.listEntryNoneTemplate 554 methList = self.listEntryNoneTemplate
512 return self.listTemplate.format(**{ \ 555 return self.listTemplate.format(**{ \
513 'Entries': methList, 556 'Entries': methList,
514 }), ''.join(methBodies) 557 }), ''.join(methBodies)
515 558
516 def __genRbModulesSection(self): 559 def __genRbModulesSection(self):
517 """ 560 """
518 Private method to generate the document section with details about Ruby modules. 561 Private method to generate the document section with details about
562 Ruby modules.
519 563
520 @return The Ruby modules details section. (string) 564 @return The Ruby modules details section. (string)
521 """ 565 """
522 rbModulesNames = sorted(list(self.module.modules.keys())) 566 rbModulesNames = sorted(list(self.module.modules.keys()))
523 rbModules = [] 567 rbModules = []
524 for rbModuleName in rbModulesNames: 568 for rbModuleName in rbModulesNames:
525 rbModule = self.module.modules[rbModuleName] 569 rbModule = self.module.modules[rbModuleName]
526 globalsList = self.__genGlobalsListSection(rbModule) 570 globalsList = self.__genGlobalsListSection(rbModule)
527 methList, methBodies = \ 571 methList, methBodies = self.__genMethodSection(
528 self.__genMethodSection(rbModule, rbModuleName, Function.General) 572 rbModule, rbModuleName, Function.General)
529 classList, classBodies = \ 573 classList, classBodies = self.__genRbModulesClassesSection(
530 self.__genRbModulesClassesSection(rbModule, rbModuleName) 574 rbModule, rbModuleName)
531 575
532 try: 576 try:
533 rbmBody = self.rbModuleTemplate.format(**{ \ 577 rbmBody = self.rbModuleTemplate.format(**{ \
534 'Anchor': rbModuleName, 578 'Anchor': rbModuleName,
535 'Module': rbModule.name, 579 'Module': rbModule.name,
536 'ModuleDescription': self.__formatDescription(rbModule.description), 580 'ModuleDescription':
581 self.__formatDescription(rbModule.description),
537 'GlobalsList': globalsList, 582 'GlobalsList': globalsList,
538 'ClassesList': classList, 583 'ClassesList': classList,
539 'ClassesDetails': classBodies, 584 'ClassesDetails': classBodies,
540 'FunctionsList': methList, 585 'FunctionsList': methList,
541 'FunctionsDetails': methBodies, 586 'FunctionsDetails': methBodies,
542 }) 587 })
543 except TagError as e: 588 except TagError as e:
544 sys.stderr.write( 589 sys.stderr.write(
545 "Error in tags of description of Ruby module {0}.\n".format( 590 "Error in tags of description of Ruby module {0}.\n"
546 rbModuleName)) 591 .format(rbModuleName))
547 sys.stderr.write("{0}\n".format(e)) 592 sys.stderr.write("{0}\n".format(e))
548 rbmBody = "" 593 rbmBody = ""
549 594
550 rbModules.append(rbmBody) 595 rbModules.append(rbmBody)
551 596
555 """ 600 """
556 Private method to generate the Ruby module classes details section. 601 Private method to generate the Ruby module classes details section.
557 602
558 @param obj Reference to the object being formatted. 603 @param obj Reference to the object being formatted.
559 @param modName Name of the Ruby module containing the classes. (string) 604 @param modName Name of the Ruby module containing the classes. (string)
560 @return The classes list and classes details section. (tuple of two string) 605 @return The classes list and classes details section.
606 (tuple of two string)
561 """ 607 """
562 classNames = sorted(list(obj.classes.keys())) 608 classNames = sorted(list(obj.classes.keys()))
563 classes = [] 609 classes = []
564 for className in classNames: 610 for className in classNames:
565 _class = obj.classes[className] 611 _class = obj.classes[className]
575 try: 621 try:
576 clsBody = self.rbModulesClassTemplate.format(**{ \ 622 clsBody = self.rbModulesClassTemplate.format(**{ \
577 'Anchor': className, 623 'Anchor': className,
578 'Class': _class.name, 624 'Class': _class.name,
579 'ClassSuper': supers, 625 'ClassSuper': supers,
580 'ClassDescription': self.__formatDescription(_class.description), 626 'ClassDescription':
627 self.__formatDescription(_class.description),
581 'MethodList': methList, 628 'MethodList': methList,
582 'MethodDetails': methBodies, 629 'MethodDetails': methBodies,
583 }) 630 })
584 except TagError as e: 631 except TagError as e:
585 sys.stderr.write("Error in tags of description of class {0}.\n".format( 632 sys.stderr.write(
633 "Error in tags of description of class {0}.\n".format(
586 className)) 634 className))
587 sys.stderr.write("{0}\n".format(e)) 635 sys.stderr.write("{0}\n".format(e))
588 clsBody = "" 636 clsBody = ""
589 637
590 classes.append(clsBody) 638 classes.append(clsBody)
591 639
592 classesList = \ 640 classesList = self.__genRbModulesClassesListSection(
593 self.__genRbModulesClassesListSection(classNames, obj.classes, modName) 641 classNames, obj.classes, modName)
594 642
595 if not classesList: 643 if not classesList:
596 classesList = self.listEntryNoneTemplate 644 classesList = self.listEntryNoneTemplate
597 return self.listTemplate.format(**{ \ 645 return self.listTemplate.format(**{ \
598 'Entries': classesList, 646 'Entries': classesList,
602 """ 650 """
603 Private method to generate the classes list section of a Ruby module. 651 Private method to generate the classes list section of a Ruby module.
604 652
605 @param names The names to appear in the list. (list of strings) 653 @param names The names to appear in the list. (list of strings)
606 @param dict A dictionary containing all relevant information. 654 @param dict A dictionary containing all relevant information.
607 @param moduleName Name of the Ruby module containing the classes. (string) 655 @param moduleName Name of the Ruby module containing the classes.
656 (string)
608 @return The list section. (string) 657 @return The list section. (string)
609 """ 658 """
610 lst = [] 659 lst = []
611 for name in names: 660 for name in names:
612 lst.append(self.listEntryTemplate.format(**{ \ 661 lst.append(self.listEntryTemplate.format(**{ \
613 'Link': "{0}.{1}".format(moduleName, name), 662 'Link': "{0}.{1}".format(moduleName, name),
614 'Name': dict[name].name, 663 'Name': dict[name].name,
615 'Description': self.__getShortDescription(dict[name].description), 664 'Description':
616 'Deprecated': self.__checkDeprecated(dict[name].description) and \ 665 self.__getShortDescription(dict[name].description),
617 self.listEntryDeprecatedTemplate or "", 666 'Deprecated':
667 self.__checkDeprecated(dict[name].description) and \
668 self.listEntryDeprecatedTemplate or "",
618 })) 669 }))
619 self.keywords.append(("{0}.{1}".format(moduleName, name), 670 self.keywords.append(("{0}.{1}".format(moduleName, name),
620 "#{0}.{1}".format(moduleName, name))) 671 "#{0}.{1}".format(moduleName, name)))
621 return ''.join(lst) 672 return ''.join(lst)
622 673
623 def __genFunctionsSection(self): 674 def __genFunctionsSection(self):
624 """ 675 """
625 Private method to generate the document section with details about functions. 676 Private method to generate the document section with details about
677 functions.
626 678
627 @return The functions details section. (string) 679 @return The functions details section. (string)
628 """ 680 """
629 funcBodies = [] 681 funcBodies = []
630 funcNames = sorted(list(self.module.functions.keys())) 682 funcNames = sorted(list(self.module.functions.keys()))
633 funcBody = self.functionTemplate.format(**{ \ 685 funcBody = self.functionTemplate.format(**{ \
634 'Anchor': funcName, 686 'Anchor': funcName,
635 'Function': self.module.functions[funcName].name, 687 'Function': self.module.functions[funcName].name,
636 'FunctionDescription': self.__formatDescription( 688 'FunctionDescription': self.__formatDescription(
637 self.module.functions[funcName].description), 689 self.module.functions[funcName].description),
638 'Params': ', '.join(self.module.functions[funcName].parameters), 690 'Params':
691 ', '.join(self.module.functions[funcName].parameters),
639 }) 692 })
640 except TagError as e: 693 except TagError as e:
641 sys.stderr.write("Error in tags of description of function {0}.\n".format( 694 sys.stderr.write(
695 "Error in tags of description of function {0}.\n".format(
642 funcName)) 696 funcName))
643 sys.stderr.write("{0}\n".format(e)) 697 sys.stderr.write("{0}\n".format(e))
644 funcBody = "" 698 funcBody = ""
645 699
646 funcBodies.append(funcBody) 700 funcBodies.append(funcBody)
666 descfound = 1 720 descfound = 1
667 dotpos = desc.find('.') 721 dotpos = desc.find('.')
668 if dotpos == -1: 722 if dotpos == -1:
669 sdlist.append(desc.strip()) 723 sdlist.append(desc.strip())
670 else: 724 else:
671 while dotpos + 1 < len(desc) and not desc[dotpos + 1].isspace(): 725 while dotpos + 1 < len(desc) and \
672 # don't recognize '.' inside a number or word as stop condition 726 not desc[dotpos + 1].isspace():
727 # don't recognize '.' inside a number or word as
728 # stop condition
673 dotpos = desc.find('.', dotpos + 1) 729 dotpos = desc.find('.', dotpos + 1)
674 if dotpos == -1: 730 if dotpos == -1:
675 break 731 break
676 if dotpos == -1: 732 if dotpos == -1:
677 sdlist.append(desc.strip()) 733 sdlist.append(desc.strip())
689 def __checkDeprecated(self, descr): 745 def __checkDeprecated(self, descr):
690 """ 746 """
691 Private method to check, if the object to be documented contains a 747 Private method to check, if the object to be documented contains a
692 deprecated flag. 748 deprecated flag.
693 749
694 @param desc The documentation string. (string) 750 @param descr documentation string (string)
695 @return Flag indicating the deprecation status. (boolean) 751 @return flag indicating the deprecation status (boolean)
696 """ 752 """
697 dlist = descr.splitlines() 753 dlist = descr.splitlines()
698 for desc in dlist: 754 for desc in dlist:
699 desc = desc.strip() 755 desc = desc.strip()
700 if desc.startswith("@deprecated"): 756 if desc.startswith("@deprecated"):
799 'Link': entry, 855 'Link': entry,
800 }) 856 })
801 857
802 def __genSeeListSection(self, _list, template): 858 def __genSeeListSection(self, _list, template):
803 """ 859 """
804 Private method to generate the "see also" list section of a description. 860 Private method to generate the "see also" list section of a
861 description.
805 862
806 @param _list List containing the info for the section. 863 @param _list List containing the info for the section.
807 @param template The template to be used for the list. (string) 864 @param template The template to be used for the list. (string)
808 @return The list section. (string) 865 @return The list section. (string)
809 """ 866 """
810 lst = [] 867 lst = []
811 for seeEntry in _list: 868 for seeEntry in _list:
812 seeEntryString = ''.join(seeEntry) 869 seeEntryString = ''.join(seeEntry)
813 lst.append(template.format(**{ \ 870 lst.append(template.format(**{ \
814 'Link': html_uencode(self.__formatCrossReferenceEntry(seeEntryString)), 871 'Link': html_uencode(self.__formatCrossReferenceEntry(
872 seeEntryString)),
815 })) 873 }))
816 return '\n'.join(lst) 874 return '\n'.join(lst)
817 875
818 def __processInlineTags(self, desc): 876 def __processInlineTags(self, desc):
819 """ 877 """
820 Private method to process inline tags. 878 Private method to process inline tags.
821 879
822 @param desc One line of the description (string) 880 @param desc One line of the description (string)
823 @return processed line with inline tags expanded (string) 881 @return processed line with inline tags expanded (string)
882 @exception TagError raised to indicate an invalid tag
824 """ 883 """
825 start = desc.find('{@') 884 start = desc.find('{@')
826 while start != -1: 885 while start != -1:
827 stop = desc.find('}', start + 2) 886 stop = desc.find('}', start + 2)
828 if stop == -1: 887 if stop == -1:
830 889
831 tagText = desc[start + 1:stop] 890 tagText = desc[start + 1:stop]
832 if tagText.startswith('@link'): 891 if tagText.startswith('@link'):
833 parts = tagText.split(None, 1) 892 parts = tagText.split(None, 1)
834 if len(parts) < 2: 893 if len(parts) < 2:
835 raise TagError("Wrong format in inline tag {0}.\n{1}".format( 894 raise TagError(
836 parts[0], desc)) 895 "Wrong format in inline tag {0}.\n{1}".format(
896 parts[0], desc))
837 897
838 formattedTag = self.__formatCrossReferenceEntry(parts[1]) 898 formattedTag = self.__formatCrossReferenceEntry(parts[1])
839 desc = desc.replace("{{{0}}}".format(tagText), formattedTag) 899 desc = desc.replace("{{{0}}}".format(tagText), formattedTag)
840 else: 900 else:
841 tag = tagText.split(None, 1)[0] 901 tag = tagText.split(None, 1)[0]
842 raise TagError("Unknown inline tag encountered, {0}.\n{1}".format( 902 raise TagError(
843 tag, desc)) 903 "Unknown inline tag encountered, {0}.\n{1}".format(
904 tag, desc))
844 905
845 start = desc.find('{@') 906 start = desc.find('{@')
846 907
847 return desc 908 return desc
848 909
876 del dlist[0] 937 del dlist[0]
877 for ditem in dlist: 938 for ditem in dlist:
878 ditem = self.__processInlineTags(ditem) 939 ditem = self.__processInlineTags(ditem)
879 desc = ditem.strip() 940 desc = ditem.strip()
880 if desc: 941 if desc:
881 if desc.startswith("@param") or desc.startswith("@keyparam"): 942 if desc.startswith(("@param", "@keyparam")):
882 inTagSection = True 943 inTagSection = True
883 parts = desc.split(None, 2) 944 parts = desc.split(None, 2)
884 if len(parts) < 2: 945 if len(parts) < 2:
885 raise TagError("Wrong format in {0} line.\n".format(parts[0])) 946 raise TagError(
947 "Wrong format in {0} line.\n".format(parts[0]))
886 paramName = parts[1] 948 paramName = parts[1]
887 if parts[0] == "@keyparam": 949 if parts[0] == "@keyparam":
888 paramName += '=' 950 paramName += '='
889 try: 951 try:
890 paramList.append([paramName, [parts[2]]]) 952 paramList.append([paramName, [parts[2]]])
891 except IndexError: 953 except IndexError:
892 paramList.append([paramName, []]) 954 paramList.append([paramName, []])
893 lastItem = paramList[-1][1] 955 lastItem = paramList[-1][1]
894 elif desc.startswith("@return"): 956 elif desc.startswith(("@return", "@ireturn")):
895 inTagSection = True 957 inTagSection = True
896 parts = desc.split(None, 1) 958 parts = desc.split(None, 1)
897 if len(parts) < 2: 959 if len(parts) < 2:
898 raise TagError("Wrong format in {0} line.\n".format(parts[0])) 960 raise TagError(
961 "Wrong format in {0} line.\n".format(parts[0]))
899 returns = [parts[1]] 962 returns = [parts[1]]
900 lastItem = returns 963 lastItem = returns
901 elif desc.startswith("@exception") or \ 964 elif desc.startswith(("@exception", "@throws", "@raise")):
902 desc.startswith("@throws") or \
903 desc.startswith("@raise"):
904 inTagSection = True 965 inTagSection = True
905 parts = desc.split(None, 2) 966 parts = desc.split(None, 2)
906 if len(parts) < 2: 967 if len(parts) < 2:
907 raise TagError("Wrong format in {0} line.\n".format(parts[0])) 968 raise TagError(
969 "Wrong format in {0} line.\n".format(parts[0]))
908 excName = parts[1] 970 excName = parts[1]
909 try: 971 try:
910 exceptionDict[excName] = [parts[2]] 972 exceptionDict[excName] = [parts[2]]
911 except IndexError: 973 except IndexError:
912 exceptionDict[excName] = [] 974 exceptionDict[excName] = []
926 lastItem = signalDict[signalName] 988 lastItem = signalDict[signalName]
927 elif desc.startswith("@event"): 989 elif desc.startswith("@event"):
928 inTagSection = True 990 inTagSection = True
929 m = _event(desc, 0) 991 m = _event(desc, 0)
930 if m is None: 992 if m is None:
931 raise TagError("Wrong format in {0} line.\n".format(parts[0])) 993 raise TagError(
994 "Wrong format in {0} line.\n".format(parts[0]))
932 eventName = 1 and m.group("EventName1") \ 995 eventName = 1 and m.group("EventName1") \
933 or m.group("EventName2") 996 or m.group("EventName2")
934 eventDesc = 1 and m.group("EventDescription1") \ 997 eventDesc = 1 and m.group("EventDescription1") \
935 or m.group("EventDescription2") 998 or m.group("EventDescription2")
936 eventDict[eventName] = [] 999 eventDict[eventName] = []
939 lastItem = eventDict[eventName] 1002 lastItem = eventDict[eventName]
940 elif desc.startswith("@deprecated"): 1003 elif desc.startswith("@deprecated"):
941 inTagSection = True 1004 inTagSection = True
942 parts = desc.split(None, 1) 1005 parts = desc.split(None, 1)
943 if len(parts) < 2: 1006 if len(parts) < 2:
944 raise TagError("Wrong format in {0} line.\n".format(parts[0])) 1007 raise TagError(
1008 "Wrong format in {0} line.\n".format(parts[0]))
945 deprecated = [parts[1]] 1009 deprecated = [parts[1]]
946 lastItem = deprecated 1010 lastItem = deprecated
947 elif desc.startswith("@author"): 1011 elif desc.startswith("@author"):
948 inTagSection = True 1012 inTagSection = True
949 parts = desc.split(None, 1) 1013 parts = desc.split(None, 1)
950 if len(parts) < 2: 1014 if len(parts) < 2:
951 raise TagError("Wrong format in {0} line.\n".format(parts[0])) 1015 raise TagError(
1016 "Wrong format in {0} line.\n".format(parts[0]))
952 authorInfo = [parts[1]] 1017 authorInfo = [parts[1]]
953 lastItem = authorInfo 1018 lastItem = authorInfo
954 elif desc.startswith("@since"): 1019 elif desc.startswith("@since"):
955 inTagSection = True 1020 inTagSection = True
956 parts = desc.split(None, 1) 1021 parts = desc.split(None, 1)
957 if len(parts) < 2: 1022 if len(parts) < 2:
958 raise TagError("Wrong format in {0} line.\n".format(parts[0])) 1023 raise TagError(
1024 "Wrong format in {0} line.\n".format(parts[0]))
959 sinceInfo = [parts[1]] 1025 sinceInfo = [parts[1]]
960 lastItem = sinceInfo 1026 lastItem = sinceInfo
961 elif desc.startswith("@see"): 1027 elif desc.startswith("@see"):
962 inTagSection = True 1028 inTagSection = True
963 parts = desc.split(None, 1) 1029 parts = desc.split(None, 1)
964 if len(parts) < 2: 1030 if len(parts) < 2:
965 raise TagError("Wrong format in {0} line.\n".format(parts[0])) 1031 raise TagError(
1032 "Wrong format in {0} line.\n".format(parts[0]))
966 seeList.append([parts[1]]) 1033 seeList.append([parts[1]])
967 lastItem = seeList[-1] 1034 lastItem = seeList[-1]
968 elif desc.startswith("@@"): 1035 elif desc.startswith("@@"):
969 lastItem.append(desc[1:]) 1036 lastItem.append(desc[1:])
970 elif desc.startswith("@"): 1037 elif desc.startswith("@"):
971 tag = desc.split(None, 1)[0] 1038 tag = desc.split(None, 1)[0]
972 raise TagError("Unknown tag encountered, {0}.\n".format(tag)) 1039 raise TagError(
1040 "Unknown tag encountered, {0}.\n".format(tag))
973 else: 1041 else:
974 lastItem.append(ditem) 1042 lastItem.append(ditem)
975 elif not inTagSection: 1043 elif not inTagSection:
976 lastItem.append(ditem) 1044 lastItem.append(ditem)
977 1045
987 }) 1055 })
988 else: 1056 else:
989 parameterSect = "" 1057 parameterSect = ""
990 1058
991 if returns: 1059 if returns:
992 returnSect = self.returnsTemplate.format(html_uencode('\n'.join(returns))) 1060 returnSect = self.returnsTemplate.format(
1061 html_uencode('\n'.join(returns)))
993 else: 1062 else:
994 returnSect = "" 1063 returnSect = ""
995 1064
996 if exceptionDict: 1065 if exceptionDict:
997 exceptionSect = self.exceptionsListTemplate.format(**{ \ 1066 exceptionSect = self.exceptionsListTemplate.format(**{ \
1038 else: 1107 else:
1039 sinceInfoSect = "" 1108 sinceInfoSect = ""
1040 1109
1041 if seeList: 1110 if seeList:
1042 seeSect = self.seeListTemplate.format(**{ \ 1111 seeSect = self.seeListTemplate.format(**{ \
1043 'Links': self.__genSeeListSection(seeList, self.seeListEntryTemplate), 1112 'Links': self.__genSeeListSection(
1113 seeList, self.seeListEntryTemplate),
1044 }) 1114 })
1045 else: 1115 else:
1046 seeSect = '' 1116 seeSect = ''
1047 1117
1048 return "{0}{1}{2}{3}{4}{5}{6}{7}{8}{9}".format( 1118 return "{0}{1}{2}{3}{4}{5}{6}{7}{8}{9}".format(
1053 1123
1054 def getQtHelpKeywords(self): 1124 def getQtHelpKeywords(self):
1055 """ 1125 """
1056 Public method to retrieve the parts for the QtHelp keywords section. 1126 Public method to retrieve the parts for the QtHelp keywords section.
1057 1127
1058 @return list of tuples containing the name (string) and the ref (string). The ref 1128 @return list of tuples containing the name (string) and the ref
1059 is without the filename part. 1129 (string). The ref is without the filename part.
1060 """ 1130 """
1061 if not self.generated: 1131 if not self.generated:
1062 self.genDocument() 1132 self.genDocument()
1063 1133
1064 return self.keywords 1134 return self.keywords

Mercurial Repository: eric

eric ide

mercurial