Mercurial Repositories > eric / file comparison

comparison: DocumentationTools/ModuleDocumentor.py

DocumentationTools/ModuleDocumentor.py

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

Mercurial Repository: eric

eric ide

mercurial