eric: comparison DocumentationTools/ModuleDocumentor.py

-:1b59c4ba121e
+:8cd4d08fa9f6
 from Utilities import html_uencode
 from Utilities.ModuleParser import RB_SOURCE
 _signal = re.compile(r"""
 ^@signal [ \t]+
 (?P<SignalName1>
 [a-zA-Z_] \w* [ \t]* \( [^)]* \)
 )
 [ \t]* (?P<SignalDescription1> .*)
 |
 ^@signal [ \t]+
 (?P<SignalName2>
 [a-zA-Z_] \w*
 )
 [ \t]+ (?P<SignalDescription2> .*)
 """, re.VERBOSE | re.DOTALL | re.MULTILINE).search
 _event = re.compile(r"""
 ^@event [ \t]+
 (?P<EventName1>
 [a-zA-Z_] \w* [ \t]* \( [^)]* \)
 )
 [ \t]* (?P<EventDescription1> .*)
 |
 ^@event [ \t]+
 (?P<EventName2>
 [a-zA-Z_] \w*
 )
 [ \t]+ (?P<EventDescription2> .*)
 """, re.VERBOSE | re.DOTALL | re.MULTILINE).search
 class TagError(Exception):
 """
 Exception class raised, if an invalid documentation tag was found.
 """
 class ModuleDocument(object):
 """
 Class implementing the builtin documentation generator.
 """
-def __init__(self, module, colors, stylesheet = None):
+def __init__(self, module, colors, stylesheet=None):
 """
 Constructor
 @param module the information of the parsed Python file
 @param colors dictionary specifying the various colors for the output
 TemplatesListsStyle.seeListEntryTemplate.format(**colors)
 self.seeLinkTemplate = TemplatesListsStyle.seeLinkTemplate.format(**colors)
 self.sinceInfoTemplate = \
 TemplatesListsStyle.sinceInfoTemplate.format(**colors)
 self.keywords = []  # list of tuples containing the name (string) and
 # the ref (string). The ref is without the filename part.
 self.generated = False
 def isEmpty(self):
 """
 Public method to generate the source code documentation.
 @return The source code documentation. (string)
 """
 doc = self.headerTemplate.format(**{ \
-'Title' : self.module.name,
+'Title': self.module.name,
-'Style' : self.stylesheet}) + \
+'Style': self.stylesheet}) + \
 self.__genModuleSection() + \
 self.footerTemplate
 self.generated = True
 return doc
 functionList = self.__genFunctionListSection()
 try:
 if self.module.type == RB_SOURCE:
 rbModulesList = self.__genRbModulesListSection()
 modBody = self.rbFileTemplate.format(**{ \
-'Module' : self.module.name,
+'Module': self.module.name,
-'ModuleDescription' : \
+'ModuleDescription': \
 self.__formatDescription(self.module.description),
-'GlobalsList' : globalsList,
+'GlobalsList': globalsList,
-'ClassList' : classList,
+'ClassList': classList,
-'RbModulesList' : rbModulesList,
+'RbModulesList': rbModulesList,
-'FunctionList' : functionList,
+'FunctionList': functionList,
 })
 else:
 modBody = self.moduleTemplate.format(**{ \
-'Module' : self.module.name,
+'Module': self.module.name,
-'ModuleDescription' : \
+'ModuleDescription': \
 self.__formatDescription(self.module.description),
-'GlobalsList' : globalsList,
+'GlobalsList': globalsList,
-'ClassList' : classList,
+'ClassList': classList,
-'FunctionList' : functionList,
+'FunctionList': functionList,
 })
 except TagError as e:
 sys.stderr.write("Error in tags of description of module {0}.\n".format(
 self.module.name))
 sys.stderr.write("{0}\n".format(e))
 else:
 rbModulesSection = ""
 return "{0}{1}{2}{3}".format(
 modBody, classesSection, rbModulesSection, functionsSection)
-def __genListSection(self, names, dict, kwSuffix = ""):
+def __genListSection(self, names, dict, kwSuffix=""):
 """
 Private method to generate a list section of the document.
 @param names The names to appear in the list. (list of strings)
 @param dict A dictionary containing all relevant information.
 @return The list section. (string)
 """
 lst = []
 for name in names:
 lst.append(self.listEntryTemplate.format(**{ \
-'Link' : "{0}".format(name),
+'Link': "{0}".format(name),
-'Name' : dict[name].name,
+'Name': dict[name].name,
-'Description' : self.__getShortDescription(dict[name].description),
+'Description': self.__getShortDescription(dict[name].description),
-'Deprecated' : self.__checkDeprecated(dict[name].description) and \
+'Deprecated': self.__checkDeprecated(dict[name].description) and \
 self.listEntryDeprecatedTemplate or "",
 }))
 if kwSuffix:
 n = "{0} ({1})".format(name, kwSuffix)
 else:
 n = "{0}".format(name)
 self.keywords.append((n, "#{0}".format(name)))
 return ''.join(lst)
-def __genGlobalsListSection(self, class_ = None):
+def __genGlobalsListSection(self, class_=None):
 """
 Private method to generate the section listing all global attributes of
 the module.
 @param class_ reference to a class object (Class)
 attrNames = []
 if class_ is not None:
 scope = class_
 else:
 scope = self.module
 attrNames = sorted([attr for attr in scope.globals.keys()
 if not scope.globals[attr].isSignal])
 if attrNames:
 s = ''.join(
-[self.listEntrySimpleTemplate.format(**{'Name' : name}) \
+[self.listEntrySimpleTemplate.format(**{'Name': name}) \
 for name in attrNames])
 else:
 s = self.listEntryNoneTemplate
 return self.listTemplate.format(**{ \
-'Entries' : s,
+'Entries': s,
 })
 def __genClassListSection(self):
 """
 Private method to generate the section listing all classes of the module.
 self.empty = False
 s = self.__genListSection(names, self.module.classes)
 else:
 s = self.listEntryNoneTemplate
 return self.listTemplate.format(**{ \
-'Entries' : s,
+'Entries': s,
 })
 def __genRbModulesListSection(self):
 """
 Private method to generate the section listing all modules of the file
 (Ruby only).
 @return The modules list section. (string)
 """
 names = sorted(list(self.module.modules.keys()))
 self.empty = False
 s = self.__genListSection(names, self.module.modules)
 else:
 s = self.listEntryNoneTemplate
 return self.listTemplate.format(**{ \
-'Entries' : s,
+'Entries': s,
 })
 def __genFunctionListSection(self):
 """
 Private method to generate the section listing all functions of the module.
 self.empty = False
 s = self.__genListSection(names, self.module.functions)
 else:
 s = self.listEntryNoneTemplate
 return self.listTemplate.format(**{ \
-'Entries' : s,
+'Entries': s,
 })
 def __genClassesSection(self):
 """
 Private method to generate the document section with details about classes.
 globalsList = self.__genGlobalsListSection(_class)
 methList, methBodies = self.__genMethodSection(_class, className)
 try:
 clsBody = self.classTemplate.format(**{ \
-'Anchor' : className,
+'Anchor': className,
-'Class' : _class.name,
+'Class': _class.name,
-'ClassSuper' : supers,
+'ClassSuper': supers,
-'ClassDescription' : self.__formatDescription(_class.description),
+'ClassDescription': self.__formatDescription(_class.description),
-'GlobalsList' : globalsList,
+'GlobalsList': globalsList,
-'MethodList' : methList,
+'MethodList': methList,
-'MethodDetails' : methBodies,
+'MethodDetails': methBodies,
 })
 except TagError as e:
 sys.stderr.write("Error in tags of description of class {0}.\n".format(
 className))
 sys.stderr.write("{0}\n".format(e))
 @return The list section. (string)
 """
 lst = []
 try:
 lst.append(self.listEntryTemplate.format(**{ \
-'Link' : "{0}.{1}".format(className, '__init__'),
+'Link': "{0}.{1}".format(className, '__init__'),
-'Name' : clsName,
+'Name': clsName,
-'Description' : self.__getShortDescription(dict['__init__'].description),
+'Description': self.__getShortDescription(dict['__init__'].description),
-'Deprecated' : self.__checkDeprecated(dict['__init__'].description) and \
+'Deprecated': self.__checkDeprecated(dict['__init__'].description) and \
 self.listEntryDeprecatedTemplate or "",
 }))
 self.keywords.append(("{0} (Constructor)".format(className),
 "#{0}.{1}".format(className, '__init__')))
 except KeyError:
 pass
 for name in names:
 lst.append(self.listEntryTemplate.format(**{ \
-'Link' : "{0}.{1}".format(className, name),
+'Link': "{0}.{1}".format(className, name),
-'Name' : dict[name].name,
+'Name': dict[name].name,
-'Description' : self.__getShortDescription(dict[name].description),
+'Description': self.__getShortDescription(dict[name].description),
-'Deprecated' : self.__checkDeprecated(dict[name].description) and \
+'Deprecated': self.__checkDeprecated(dict[name].description) and \
 self.listEntryDeprecatedTemplate or "",
 }))
 self.keywords.append(("{0}.{1}".format(className, name),
 "#{0}.{1}".format(className, name)))
 return ''.join(lst)
 def __genMethodSection(self, obj, className):
 """
 methods = sorted(list(obj.methods.keys()))
 if '__init__' in methods:
 methods.remove('__init__')
 try:
 methBody = self.constructorTemplate.format(**{ \
-'Anchor' : className,
+'Anchor': className,
-'Class' : obj.name,
+'Class': obj.name,
-'Method' : '__init__',
+'Method': '__init__',
-'MethodDescription' : \
+'MethodDescription': \
 self.__formatDescription(obj.methods['__init__'].description),
-'Params' : ', '.join(obj.methods['__init__'].parameters[1:]),
+'Params': ', '.join(obj.methods['__init__'].parameters[1:]),
 })
 except TagError as e:
 sys.stderr.write(
 "Error in tags of description of method {0}.{1}.\n".format(
 className, '__init__'))
 methBodies.append(methBody)
 for method in methods:
 try:
 methBody = self.methodTemplate.format(**{ \
-'Anchor' : className,
+'Anchor': className,
-'Class' : obj.name,
+'Class': obj.name,
-'Method' : obj.methods[method].name,
+'Method': obj.methods[method].name,
-'MethodDescription' : \
+'MethodDescription': \
 self.__formatDescription(obj.methods[method].description),
-'Params' : ', '.join(obj.methods[method].parameters[1:]),
+'Params': ', '.join(obj.methods[method].parameters[1:]),
 })
 except TagError as e:
 sys.stderr.write(
 "Error in tags of description of method {0}.{1}.\n".format(
 className, method))
 methList = self.__genMethodsListSection(methods, obj.methods, className, obj.name)
 if not methList:
 methList = self.listEntryNoneTemplate
 return self.listTemplate.format(**{ \
-'Entries' : methList,
+'Entries': methList,
 }), ''.join(methBodies)
 def __genRbModulesSection(self):
 """
 Private method to generate the document section with details about Ruby modules.
 classList, classBodies = \
 self.__genRbModulesClassesSection(rbModule, rbModuleName)
 try:
 rbmBody = self.rbModuleTemplate.format(**{ \
-'Anchor' : rbModuleName,
+'Anchor': rbModuleName,
-'Module' : rbModule.name,
+'Module': rbModule.name,
-'ModuleDescription' : self.__formatDescription(rbModule.description),
+'ModuleDescription': self.__formatDescription(rbModule.description),
-'GlobalsList' : globalsList,
+'GlobalsList': globalsList,
-'ClassesList' : classList,
+'ClassesList': classList,
-'ClassesDetails' : classBodies,
+'ClassesDetails': classBodies,
-'FunctionsList' : methList,
+'FunctionsList': methList,
-'FunctionsDetails' : methBodies,
+'FunctionsDetails': methBodies,
 })
 except TagError as e:
 sys.stderr.write(
 "Error in tags of description of Ruby module {0}.\n".format(
 rbModuleName))
 methList, methBodies = self.__genMethodSection(_class, className)
 try:
 clsBody = self.rbModulesClassTemplate.format(**{ \
-'Anchor' : className,
+'Anchor': className,
-'Class' : _class.name,
+'Class': _class.name,
-'ClassSuper' : supers,
+'ClassSuper': supers,
-'ClassDescription' : self.__formatDescription(_class.description),
+'ClassDescription': self.__formatDescription(_class.description),
-'MethodList' : methList,
+'MethodList': methList,
-'MethodDetails' : methBodies,
+'MethodDetails': methBodies,
 })
 except TagError as e:
 sys.stderr.write("Error in tags of description of class {0}.\n".format(
 className))
 sys.stderr.write("{0}\n".format(e))
 clsBody = ""
 classes.append(clsBody)
 classesList = \
 self.__genRbModulesClassesListSection(classNames, obj.classes, modName)
 if not classesList:
 classesList = self.listEntryNoneTemplate
 return self.listTemplate.format(**{ \
-'Entries' : classesList,
+'Entries': classesList,
 }), ''.join(classes)
 def __genRbModulesClassesListSection(self, names, dict, moduleName):
 """
 Private method to generate the classes list section of a Ruby module.
 @return The list section. (string)
 """
 lst = []
 for name in names:
 lst.append(self.listEntryTemplate.format(**{ \
-'Link' : "{0}.{1}".format(moduleName, name),
+'Link': "{0}.{1}".format(moduleName, name),
-'Name' : dict[name].name,
+'Name': dict[name].name,
-'Description' : self.__getShortDescription(dict[name].description),
+'Description': self.__getShortDescription(dict[name].description),
-'Deprecated' : self.__checkDeprecated(dict[name].description) and \
+'Deprecated': self.__checkDeprecated(dict[name].description) and \
 self.listEntryDeprecatedTemplate or "",
 }))
 self.keywords.append(("{0}.{1}".format(moduleName, name),
 "#{0}.{1}".format(moduleName, name)))
 return ''.join(lst)
 def __genFunctionsSection(self):
 """
 funcBodies = []
 funcNames = sorted(list(self.module.functions.keys()))
 for funcName in funcNames:
 try:
 funcBody = self.functionTemplate.format(**{ \
-'Anchor' : funcName,
+'Anchor': funcName,
-'Function' : self.module.functions[funcName].name,
+'Function': self.module.functions[funcName].name,
-'FunctionDescription' : self.__formatDescription(
+'FunctionDescription': self.__formatDescription(
 self.module.functions[funcName].description),
-'Params' : ', '.join(self.module.functions[funcName].parameters),
+'Params': ', '.join(self.module.functions[funcName].parameters),
 })
 except TagError as e:
 sys.stderr.write("Error in tags of description of function {0}.\n".format(
 funcName))
 sys.stderr.write("{0}\n".format(e))
 descfound = 1
 dotpos = desc.find('.')
 if dotpos == -1:
 sdlist.append(desc.strip())
 else:
-while dotpos+1 < len(desc) and not desc[dotpos+1].isspace():
+while dotpos + 1 < len(desc) and not desc[dotpos + 1].isspace():
 # don't recognize '.' inside a number or word as stop condition
-dotpos = desc.find('.', dotpos+1)
+dotpos = desc.find('.', dotpos + 1)
 if dotpos == -1:
 break
 if dotpos == -1:
 sdlist.append(desc.strip())
 else:
-sdlist.append(desc[:dotpos+1].strip())
+sdlist.append(desc[:dotpos + 1].strip())
 break   # break if a '.' is found
 else:
 if descfound:
 break   # break if an empty line is found
 if sdlist:
 else:
 return ''
 def __checkDeprecated(self, descr):
 """
 Private method to check, if the object to be documented contains a
 deprecated flag.
 @param desc The documentation string. (string)
 @return Flag indicating the deprecation status. (boolean)
 """
 linelist.append("")
 else:
 linelist.append(html_uencode(line))
 else:
 lst.append(self.paragraphTemplate.format(**{ \
-'Lines' : '\n'.join(linelist)
+'Lines': '\n'.join(linelist)
 }))
 linelist = []
 if linelist:
 lst.append(self.paragraphTemplate.format(**{ \
-'Lines' : '\n'.join(linelist)
+'Lines': '\n'.join(linelist)
 }))
 return ''.join(lst)
 def __genDescriptionListSection(self, dictionary, template):
 """
 """
 lst = []
 keys = sorted(list(dictionary.keys()))
 for key in keys:
 lst.append(template.format(**{ \
-'Name' : key,
+'Name': key,
-'Description' : html_uencode('\n'.join(dictionary[key])),
+'Description': html_uencode('\n'.join(dictionary[key])),
 }))
 return ''.join(lst)
 def __genParamDescriptionListSection(self, _list, template):
 """
 @return The list section. (string)
 """
 lst = []
 for name, lines in _list:
 lst.append(template.format(**{ \
-'Name' : name,
+'Name': name,
-'Description' : html_uencode('\n'.join(lines)),
+'Description': html_uencode('\n'.join(lines)),
 }))
 return ''.join(lst)
 def __formatCrossReferenceEntry(self, entry):
 """
 if anchor:
 reference = "{0}#{1}".format(reference, anchor)
 entry = 'href="{0}">{1}</a>'.format(reference, label)
 return self.seeLinkTemplate.format(**{ \
-'Link' : entry,
+'Link': entry,
 })
 def __genSeeListSection(self, _list, template):
 """
 Private method to generate the "see also" list section of a description.
 """
 lst = []
 for seeEntry in _list:
 seeEntryString = ''.join(seeEntry)
 lst.append(template.format(**{ \
-'Link' : html_uencode(self.__formatCrossReferenceEntry(seeEntryString)),
+'Link': html_uencode(self.__formatCrossReferenceEntry(seeEntryString)),
 }))
 return '\n'.join(lst)
 def __processInlineTags(self, desc):
 """
 except IndexError:
 exceptionDict[excName] = []
 lastItem = exceptionDict[excName]
 elif desc.startswith("@signal"):
 inTagSection = True
-m = _signal(desc,0)
+m = _signal(desc, 0)
 if m is None:
 raise TagError("Wrong format in {0} line.\n".format(parts[0]))
 signalName = 1 and m.group("SignalName1") \
 or m.group("SignalName2")
 signalDesc = 1 and m.group("SignalDescription1") \
 if signalDesc is not None:
 signalDict[signalName].append(signalDesc)
 lastItem = signalDict[signalName]
 elif desc.startswith("@event"):
 inTagSection = True
-m = _event(desc,0)
+m = _event(desc, 0)
 if m is None:
 raise TagError("Wrong format in {0} line.\n".format(parts[0]))
 eventName = 1 and m.group("EventName1") \
 or m.group("EventName2")
 eventDesc = 1 and m.group("EventDescription1") \
 else:
 description = ""
 if paramList:
 parameterSect = self.parametersListTemplate.format(**{ \
-'Parameters' : self.__genParamDescriptionListSection(paramList,
+'Parameters': self.__genParamDescriptionListSection(paramList,
 self.parametersListEntryTemplate)
 })
 else:
 parameterSect = ""
 else:
 returnSect = ""
 if exceptionDict:
 exceptionSect = self.exceptionsListTemplate.format(**{ \
-'Exceptions' : self.__genDescriptionListSection(exceptionDict,
+'Exceptions': self.__genDescriptionListSection(exceptionDict,
 self.exceptionsListEntryTemplate)
 })
 else:
 exceptionSect = ""
 if signalDict:
 signalSect = self.signalsListTemplate.format(**{ \
-'Signals' : self.__genDescriptionListSection(signalDict,
+'Signals': self.__genDescriptionListSection(signalDict,
 self.signalsListEntryTemplate)
 })
 else:
 signalSect = ""
 if eventDict:
 eventSect = self.eventsListTemplate.format(**{ \
-'Events' : self.__genDescriptionListSection(eventDict,
+'Events': self.__genDescriptionListSection(eventDict,
 self.eventsListEntryTemplate)
 })
 else:
 eventSect = ""
 if deprecated:
 deprecatedSect = self.deprecatedTemplate.format(**{ \
-'Lines' : html_uencode('\n'.join(deprecated)),
+'Lines': html_uencode('\n'.join(deprecated)),
 })
 else:
 deprecatedSect = ""
 if authorInfo:
 authorInfoSect = self.authorInfoTemplate.format(**{ \
-'Authors' : html_uencode('\n'.join(authorInfo)),
+'Authors': html_uencode('\n'.join(authorInfo)),
 })
 else:
 authorInfoSect = ""
 if sinceInfo:
 sinceInfoSect = self.sinceInfoTemplate.format(**{ \
-'Info' : html_uencode(sinceInfo[0]),
+'Info': html_uencode(sinceInfo[0]),
 })
 else:
 sinceInfoSect = ""
 if seeList:
 seeSect = self.seeListTemplate.format(**{ \
-'Links' : self.__genSeeListSection(seeList, self.seeListEntryTemplate),
+'Links': self.__genSeeListSection(seeList, self.seeListEntryTemplate),
 })
 else:
 seeSect = ''
 return "{0}{1}{2}{3}{4}{5}{6}{7}{8}{9}".format(

Mercurial Repositories > eric / file comparison

comparison: DocumentationTools/ModuleDocumentor.py

DocumentationTools/ModuleDocumentor.py