Mercurial Repositories > eric / file comparison

comparison: DocumentationTools/ModuleDocumentor.py

DocumentationTools/ModuleDocumentor.py

changeset 4267
94496d77156b
parent 4021
195a471c327b
child 4631
5c1a96925da4
equal deleted inserted replaced
4266:17c215c416ba 4267:94496d77156b
98 self.listEntrySimpleTemplate = \ 98 self.listEntrySimpleTemplate = \
99 TemplatesListsStyleCSS.listEntrySimpleTemplate 99 TemplatesListsStyleCSS.listEntrySimpleTemplate
100 self.paragraphTemplate = TemplatesListsStyleCSS.paragraphTemplate 100 self.paragraphTemplate = TemplatesListsStyleCSS.paragraphTemplate
101 self.parametersListTemplate = \ 101 self.parametersListTemplate = \
102 TemplatesListsStyleCSS.parametersListTemplate 102 TemplatesListsStyleCSS.parametersListTemplate
103 self.parameterTypesListEntryTemplate = \
104 TemplatesListsStyleCSS.parameterTypesListEntryTemplate
103 self.parametersListEntryTemplate = \ 105 self.parametersListEntryTemplate = \
104 TemplatesListsStyleCSS.parametersListEntryTemplate 106 TemplatesListsStyleCSS.parametersListEntryTemplate
105 self.returnsTemplate = TemplatesListsStyleCSS.returnsTemplate 107 self.returnsTemplate = TemplatesListsStyleCSS.returnsTemplate
108 self.returnTypesTemplate = \
109 TemplatesListsStyleCSS.returnTypesTemplate
106 self.exceptionsListTemplate = \ 110 self.exceptionsListTemplate = \
107 TemplatesListsStyleCSS.exceptionsListTemplate 111 TemplatesListsStyleCSS.exceptionsListTemplate
108 self.exceptionsListEntryTemplate = \ 112 self.exceptionsListEntryTemplate = \
109 TemplatesListsStyleCSS.exceptionsListEntryTemplate 113 TemplatesListsStyleCSS.exceptionsListEntryTemplate
110 self.signalsListTemplate = \ 114 self.signalsListTemplate = \
159 self.parametersListTemplate = \ 163 self.parametersListTemplate = \
160 TemplatesListsStyle.parametersListTemplate.format(**colors) 164 TemplatesListsStyle.parametersListTemplate.format(**colors)
161 self.parametersListEntryTemplate = \ 165 self.parametersListEntryTemplate = \
162 TemplatesListsStyle.parametersListEntryTemplate.format( 166 TemplatesListsStyle.parametersListEntryTemplate.format(
163 **colors) 167 **colors)
168 self.parameterTypesListEntryTemplate = \
169 TemplatesListsStyle.parameterTypesListEntryTemplate.format(
170 **colors)
164 self.returnsTemplate = \ 171 self.returnsTemplate = \
165 TemplatesListsStyle.returnsTemplate.format(**colors) 172 TemplatesListsStyle.returnsTemplate.format(**colors)
173 self.returnTypesTemplate = \
174 TemplatesListsStyle.returnTypesTemplate.format(**colors)
166 self.exceptionsListTemplate = \ 175 self.exceptionsListTemplate = \
167 TemplatesListsStyle.exceptionsListTemplate.format(**colors) 176 TemplatesListsStyle.exceptionsListTemplate.format(**colors)
168 self.exceptionsListEntryTemplate = \ 177 self.exceptionsListEntryTemplate = \
169 TemplatesListsStyle.exceptionsListEntryTemplate.format( 178 TemplatesListsStyle.exceptionsListEntryTemplate.format(
170 **colors) 179 **colors)
275 'ClassList': classList, 284 'ClassList': classList,
276 'FunctionList': functionList, 285 'FunctionList': functionList,
277 }) 286 })
278 except TagError as e: 287 except TagError as e:
279 sys.stderr.write( 288 sys.stderr.write(
289 "Error processing {0}.\n".format(self.module.file))
290 sys.stderr.write(
280 "Error in tags of description of module {0}.\n".format( 291 "Error in tags of description of module {0}.\n".format(
281 self.module.name)) 292 self.module.name))
282 sys.stderr.write("{0}\n".format(e)) 293 sys.stderr.write("{0}\n".format(e))
283 return "" 294 return ""
284 295
424 'StaticMethodList': staticMethList, 435 'StaticMethodList': staticMethList,
425 'MethodDetails': 436 'MethodDetails':
426 classMethBodies + methBodies + staticMethBodies, 437 classMethBodies + methBodies + staticMethBodies,
427 }) 438 })
428 except TagError as e: 439 except TagError as e:
440 sys.stderr.write(
441 "Error processing {0}.\n".format(self.module.file))
429 sys.stderr.write( 442 sys.stderr.write(
430 "Error in tags of description of class {0}.\n".format( 443 "Error in tags of description of class {0}.\n".format(
431 className)) 444 className))
432 sys.stderr.write("{0}\n".format(e)) 445 sys.stderr.write("{0}\n".format(e))
433 clsBody = "" 446 clsBody = ""
507 'Params': 520 'Params':
508 ', '.join(obj.methods['__init__'].parameters[1:]), 521 ', '.join(obj.methods['__init__'].parameters[1:]),
509 }) 522 })
510 except TagError as e: 523 except TagError as e:
511 sys.stderr.write( 524 sys.stderr.write(
525 "Error processing {0}.\n".format(self.module.file))
526 sys.stderr.write(
512 "Error in tags of description of method {0}.{1}.\n".format( 527 "Error in tags of description of method {0}.{1}.\n".format(
513 className, '__init__')) 528 className, '__init__'))
514 sys.stderr.write("{0}\n".format(e)) 529 sys.stderr.write("{0}\n".format(e))
515 methBody = "" 530 methBody = ""
516 methBodies.append(methBody) 531 methBodies.append(methBody)
533 obj.methods[method].description), 548 obj.methods[method].description),
534 'Params': ', '.join(obj.methods[method].parameters[1:]), 549 'Params': ', '.join(obj.methods[method].parameters[1:]),
535 }) 550 })
536 except TagError as e: 551 except TagError as e:
537 sys.stderr.write( 552 sys.stderr.write(
553 "Error processing {0}.\n".format(self.module.file))
554 sys.stderr.write(
538 "Error in tags of description of method {0}.{1}.\n".format( 555 "Error in tags of description of method {0}.{1}.\n".format(
539 className, method)) 556 className, method))
540 sys.stderr.write("{0}\n".format(e)) 557 sys.stderr.write("{0}\n".format(e))
541 methBody = "" 558 methBody = ""
542 methBodies.append(methBody) 559 methBodies.append(methBody)
579 'FunctionsList': methList, 596 'FunctionsList': methList,
580 'FunctionsDetails': methBodies, 597 'FunctionsDetails': methBodies,
581 }) 598 })
582 except TagError as e: 599 except TagError as e:
583 sys.stderr.write( 600 sys.stderr.write(
601 "Error processing {0}.\n".format(self.module.file))
602 sys.stderr.write(
584 "Error in tags of description of Ruby module {0}.\n" 603 "Error in tags of description of Ruby module {0}.\n"
585 .format(rbModuleName)) 604 .format(rbModuleName))
586 sys.stderr.write("{0}\n".format(e)) 605 sys.stderr.write("{0}\n".format(e))
587 rbmBody = "" 606 rbmBody = ""
588 607
621 self.__formatDescription(_class.description), 640 self.__formatDescription(_class.description),
622 'MethodList': methList, 641 'MethodList': methList,
623 'MethodDetails': methBodies, 642 'MethodDetails': methBodies,
624 }) 643 })
625 except TagError as e: 644 except TagError as e:
645 sys.stderr.write(
646 "Error processing {0}.\n".format(self.module.file))
626 sys.stderr.write( 647 sys.stderr.write(
627 "Error in tags of description of class {0}.\n".format( 648 "Error in tags of description of class {0}.\n".format(
628 className)) 649 className))
629 sys.stderr.write("{0}\n".format(e)) 650 sys.stderr.write("{0}\n".format(e))
630 clsBody = "" 651 clsBody = ""
682 self.module.functions[funcName].description), 703 self.module.functions[funcName].description),
683 'Params': 704 'Params':
684 ', '.join(self.module.functions[funcName].parameters), 705 ', '.join(self.module.functions[funcName].parameters),
685 }) 706 })
686 except TagError as e: 707 except TagError as e:
708 sys.stderr.write(
709 "Error processing {0}.\n".format(self.module.file))
687 sys.stderr.write( 710 sys.stderr.write(
688 "Error in tags of description of function {0}.\n".format( 711 "Error in tags of description of function {0}.\n".format(
689 funcName)) 712 funcName))
690 sys.stderr.write("{0}\n".format(e)) 713 sys.stderr.write("{0}\n".format(e))
691 funcBody = "" 714 funcBody = ""
794 **{'Name': key, 817 **{'Name': key,
795 'Description': html_uencode('\n'.join(dictionary[key])), 818 'Description': html_uencode('\n'.join(dictionary[key])),
796 })) 819 }))
797 return ''.join(lst) 820 return ''.join(lst)
798 821
799 def __genParamDescriptionListSection(self, _list, template): 822 def __genParamDescriptionListSection(self, _list):
800 """ 823 """
801 Private method to generate the list section of a description. 824 Private method to generate the list section of a description.
802 825
803 @param _list List containing the info for the 826 @param _list list containing the info for the parameter description
804 list section. 827 list section (list of lists with three elements)
805 @param template The template to be used for the list. (string) 828 @return formatted list section (string)
806 @return The list section. (string)
807 """ 829 """
808 lst = [] 830 lst = []
809 for name, lines in _list: 831 for name, type_, lines in _list:
810 lst.append(template.format( 832 if type_:
811 **{'Name': name, 833 lst.append(self.parameterTypesListEntryTemplate.format(
812 'Description': html_uencode('\n'.join(lines)), 834 **{'Name': name,
813 })) 835 'Type': type_,
836 'Description': html_uencode('\n'.join(lines)),
837 }))
838 else:
839 lst.append(self.parametersListEntryTemplate.format(
840 **{'Name': name,
841 'Description': html_uencode('\n'.join(lines)),
842 }))
814 return ''.join(lst) 843 return ''.join(lst)
815 844
816 def __formatCrossReferenceEntry(self, entry): 845 def __formatCrossReferenceEntry(self, entry):
817 """ 846 """
818 Private method to format a cross reference entry. 847 Private method to format a cross reference entry.
909 return "" 938 return ""
910 939
911 paragraphs = [] 940 paragraphs = []
912 paramList = [] 941 paramList = []
913 returns = [] 942 returns = []
943 returnTypes = []
914 exceptionDict = {} 944 exceptionDict = {}
915 signalDict = {} 945 signalDict = {}
916 eventDict = {} 946 eventDict = {}
917 deprecated = [] 947 deprecated = []
918 authorInfo = [] 948 authorInfo = []
922 inTagSection = False 952 inTagSection = False
923 953
924 dlist = descr.splitlines() 954 dlist = descr.splitlines()
925 while dlist and not dlist[0]: 955 while dlist and not dlist[0]:
926 del dlist[0] 956 del dlist[0]
957 lastTag = ""
927 for ditem in dlist: 958 for ditem in dlist:
928 ditem = self.__processInlineTags(ditem) 959 ditem = self.__processInlineTags(ditem)
929 desc = ditem.strip() 960 desc = ditem.strip()
930 if desc: 961 if desc:
931 if desc.startswith(("@param", "@keyparam")): 962 if desc.startswith(("@param", "@keyparam")):
932 inTagSection = True 963 inTagSection = True
933 parts = desc.split(None, 2) 964 parts = desc.split(None, 2)
965 lastTag = parts[0]
934 if len(parts) < 2: 966 if len(parts) < 2:
935 raise TagError( 967 raise TagError(
936 "Wrong format in {0} line.\n".format(parts[0])) 968 "Wrong format in {0} line.\n".format(parts[0]))
937 paramName = parts[1] 969 paramName = parts[1]
938 if parts[0] == "@keyparam": 970 if parts[0] == "@keyparam":
939 paramName += '=' 971 paramName += '='
940 try: 972 try:
941 paramList.append([paramName, [parts[2]]]) 973 paramList.append([paramName, "", [parts[2]]])
942 except IndexError: 974 except IndexError:
943 paramList.append([paramName, []]) 975 paramList.append([paramName, "", []])
944 lastItem = paramList[-1][1] 976 lastItem = paramList[-1][2]
977 elif desc.startswith("@type"):
978 if lastTag not in ["@param", "@keyparam"]:
979 raise TagError(
980 "{0} line must be preceded by a parameter line\n"
981 .format(parts[0]))
982 inTagSection = True
983 parts = desc.split(None, 1)
984 lastTag = parts[0]
985 if len(parts) < 2:
986 raise TagError(
987 "Wrong format in {0} line.\n".format(parts[0]))
988 paramList[-1][1] = parts[1]
989 elif desc.startswith("@ptype"):
990 inTagSection = True
991 parts = desc.split(None, 2)
992 lastTag = parts[0]
993 if len(parts) < 3:
994 raise TagError(
995 "Wrong format in {0} line.\n".format(parts[0]))
996 param, type_ = parts[1:]
997 for index in range(len(paramList)):
998 if paramList[index][0] == param:
999 paramList[index][1] = type_
1000 break
1001 else:
1002 raise TagError(
1003 "Unknow parameter name '{0}' in {1} line.\n"
1004 .format(param, parts[0]))
945 elif desc.startswith(("@return", "@ireturn")): 1005 elif desc.startswith(("@return", "@ireturn")):
946 inTagSection = True 1006 inTagSection = True
947 parts = desc.split(None, 1) 1007 parts = desc.split(None, 1)
1008 lastTag = parts[0]
948 if len(parts) < 2: 1009 if len(parts) < 2:
949 raise TagError( 1010 raise TagError(
950 "Wrong format in {0} line.\n".format(parts[0])) 1011 "Wrong format in {0} line.\n".format(parts[0]))
951 returns = [parts[1]] 1012 returns = [parts[1]]
952 lastItem = returns 1013 lastItem = returns
1014 elif desc.startswith("@rtype"):
1015 inTagSection = True
1016 parts = desc.split(None, 1)
1017 lastTag = parts[0]
1018 if len(parts) < 2:
1019 raise TagError(
1020 "Wrong format in {0} line.\n".format(parts[0]))
1021 returnTypes = [parts[1]]
1022 lastItem = returnTypes
953 elif desc.startswith(("@exception", "@throws", "@raise")): 1023 elif desc.startswith(("@exception", "@throws", "@raise")):
954 inTagSection = True 1024 inTagSection = True
955 parts = desc.split(None, 2) 1025 parts = desc.split(None, 2)
1026 lastTag = parts[0]
956 if len(parts) < 2: 1027 if len(parts) < 2:
957 raise TagError( 1028 raise TagError(
958 "Wrong format in {0} line.\n".format(parts[0])) 1029 "Wrong format in {0} line.\n".format(parts[0]))
959 excName = parts[1] 1030 excName = parts[1]
960 try: 1031 try:
962 except IndexError: 1033 except IndexError:
963 exceptionDict[excName] = [] 1034 exceptionDict[excName] = []
964 lastItem = exceptionDict[excName] 1035 lastItem = exceptionDict[excName]
965 elif desc.startswith("@signal"): 1036 elif desc.startswith("@signal"):
966 inTagSection = True 1037 inTagSection = True
1038 lastTag = desc.split(None, 1)[0]
967 m = _signal(desc, 0) 1039 m = _signal(desc, 0)
968 if m is None: 1040 if m is None:
969 raise TagError("Wrong format in @signal line.\n") 1041 raise TagError("Wrong format in @signal line.\n")
970 signalName = 1 and m.group("SignalName1") \ 1042 signalName = 1 and m.group("SignalName1") \
971 or m.group("SignalName2") 1043 or m.group("SignalName2")
975 if signalDesc is not None: 1047 if signalDesc is not None:
976 signalDict[signalName].append(signalDesc) 1048 signalDict[signalName].append(signalDesc)
977 lastItem = signalDict[signalName] 1049 lastItem = signalDict[signalName]
978 elif desc.startswith("@event"): 1050 elif desc.startswith("@event"):
979 inTagSection = True 1051 inTagSection = True
1052 lastTag = desc.split(None, 1)[0]
980 m = _event(desc, 0) 1053 m = _event(desc, 0)
981 if m is None: 1054 if m is None:
982 raise TagError( 1055 raise TagError(
983 "Wrong format in {0} line.\n".format(parts[0])) 1056 "Wrong format in {0} line.\n".format(parts[0]))
984 eventName = 1 and m.group("EventName1") \ 1057 eventName = 1 and m.group("EventName1") \
990 eventDict[eventName].append(eventDesc) 1063 eventDict[eventName].append(eventDesc)
991 lastItem = eventDict[eventName] 1064 lastItem = eventDict[eventName]
992 elif desc.startswith("@deprecated"): 1065 elif desc.startswith("@deprecated"):
993 inTagSection = True 1066 inTagSection = True
994 parts = desc.split(None, 1) 1067 parts = desc.split(None, 1)
1068 lastTag = parts[0]
995 if len(parts) < 2: 1069 if len(parts) < 2:
996 raise TagError( 1070 raise TagError(
997 "Wrong format in {0} line.\n".format(parts[0])) 1071 "Wrong format in {0} line.\n".format(parts[0]))
998 deprecated = [parts[1]] 1072 deprecated = [parts[1]]
999 lastItem = deprecated 1073 lastItem = deprecated
1000 elif desc.startswith("@author"): 1074 elif desc.startswith("@author"):
1001 inTagSection = True 1075 inTagSection = True
1002 parts = desc.split(None, 1) 1076 parts = desc.split(None, 1)
1077 lastTag = parts[0]
1003 if len(parts) < 2: 1078 if len(parts) < 2:
1004 raise TagError( 1079 raise TagError(
1005 "Wrong format in {0} line.\n".format(parts[0])) 1080 "Wrong format in {0} line.\n".format(parts[0]))
1006 authorInfo = [parts[1]] 1081 authorInfo = [parts[1]]
1007 lastItem = authorInfo 1082 lastItem = authorInfo
1008 elif desc.startswith("@since"): 1083 elif desc.startswith("@since"):
1009 inTagSection = True 1084 inTagSection = True
1010 parts = desc.split(None, 1) 1085 parts = desc.split(None, 1)
1086 lastTag = parts[0]
1011 if len(parts) < 2: 1087 if len(parts) < 2:
1012 raise TagError( 1088 raise TagError(
1013 "Wrong format in {0} line.\n".format(parts[0])) 1089 "Wrong format in {0} line.\n".format(parts[0]))
1014 sinceInfo = [parts[1]] 1090 sinceInfo = [parts[1]]
1015 lastItem = sinceInfo 1091 lastItem = sinceInfo
1016 elif desc.startswith("@see"): 1092 elif desc.startswith("@see"):
1017 inTagSection = True 1093 inTagSection = True
1018 parts = desc.split(None, 1) 1094 parts = desc.split(None, 1)
1095 lastTag = parts[0]
1019 if len(parts) < 2: 1096 if len(parts) < 2:
1020 raise TagError( 1097 raise TagError(
1021 "Wrong format in {0} line.\n".format(parts[0])) 1098 "Wrong format in {0} line.\n".format(parts[0]))
1022 seeList.append([parts[1]]) 1099 seeList.append([parts[1]])
1023 lastItem = seeList[-1] 1100 lastItem = seeList[-1]
1038 description = "" 1115 description = ""
1039 1116
1040 if paramList: 1117 if paramList:
1041 parameterSect = self.parametersListTemplate.format( 1118 parameterSect = self.parametersListTemplate.format(
1042 **{'Parameters': self.__genParamDescriptionListSection( 1119 **{'Parameters': self.__genParamDescriptionListSection(
1043 paramList, self.parametersListEntryTemplate)}) 1120 paramList)})
1044 else: 1121 else:
1045 parameterSect = "" 1122 parameterSect = ""
1046 1123
1047 if returns: 1124 if returns:
1048 returnSect = self.returnsTemplate.format( 1125 returnSect = self.returnsTemplate.format(
1049 html_uencode('\n'.join(returns))) 1126 html_uencode('\n'.join(returns)))
1050 else: 1127 else:
1051 returnSect = "" 1128 returnSect = ""
1129
1130 if returnTypes:
1131 returnTypesSect = self.returnTypesTemplate.format(
1132 html_uencode('\n'.join(returnTypes)))
1133 else:
1134 returnTypesSect = ""
1052 1135
1053 if exceptionDict: 1136 if exceptionDict:
1054 exceptionSect = self.exceptionsListTemplate.format( 1137 exceptionSect = self.exceptionsListTemplate.format(
1055 **{'Exceptions': self.__genDescriptionListSection( 1138 **{'Exceptions': self.__genDescriptionListSection(
1056 exceptionDict, self.exceptionsListEntryTemplate)}) 1139 exceptionDict, self.exceptionsListEntryTemplate)})
1094 **{'Links': self.__genSeeListSection( 1177 **{'Links': self.__genSeeListSection(
1095 seeList, self.seeListEntryTemplate)}) 1178 seeList, self.seeListEntryTemplate)})
1096 else: 1179 else:
1097 seeSect = '' 1180 seeSect = ''
1098 1181
1099 return "{0}{1}{2}{3}{4}{5}{6}{7}{8}{9}".format( 1182 return "{0}{1}{2}{3}{4}{5}{6}{7}{8}{9}{10}".format(
1100 deprecatedSect, description, parameterSect, returnSect, 1183 deprecatedSect, description, parameterSect, returnSect,
1101 exceptionSect, signalSect, eventSect, authorInfoSect, 1184 returnTypesSect, exceptionSect, signalSect, eventSect,
1102 seeSect, sinceInfoSect 1185 authorInfoSect, seeSect, sinceInfoSect,
1103 ) 1186 )
1104 1187
1105 def getQtHelpKeywords(self): 1188 def getQtHelpKeywords(self):
1106 """ 1189 """
1107 Public method to retrieve the parts for the QtHelp keywords section. 1190 Public method to retrieve the parts for the QtHelp keywords section.

Mercurial Repository: eric

eric ide

mercurial