def __genParagraphs(self, lines): """ Private method to assemble the descriptive paragraphs of a docstring. A paragraph is made up of a number of consecutive lines without an intermediate empty line. Empty lines are treated as a paragraph delimiter. @param lines A list of individual lines. (list of strings) @return Ready formatted paragraphs. (string) """ lst = [] linelist = [] for line in lines: if line.strip(): if line == '.': linelist.append("") else: linelist.append(html_uencode(line)) else: lst.append( self.paragraphTemplate.format( **{'Lines': '\n'.join(linelist)})) linelist = [] if linelist: lst.append( self.paragraphTemplate.format( **{'Lines': '\n'.join(linelist)})) return ''.join(lst)
def __genParagraphs(self, lines): """ Private method to assemble the descriptive paragraphs of a docstring. A paragraph is made up of a number of consecutive lines without an intermediate empty line. Empty lines are treated as a paragraph delimiter. @param lines A list of individual lines. (list of strings) @return Ready formatted paragraphs. (string) """ lst = [] linelist = [] for line in lines: if line.strip(): if line == '.': linelist.append("") else: linelist.append(html_uencode(line)) else: lst.append(self.paragraphTemplate % { \ 'Lines' : '\n'.join(linelist) }) linelist = [] if linelist: lst.append(self.paragraphTemplate % { \ 'Lines' : '\n'.join(linelist) }) return ''.join(lst)
def __genParamDescriptionListSection(self, _list): """ Private method to generate the list section of a description. @param _list list containing the info for the parameter description list section (list of lists with three elements) @return formatted list section (string) """ lst = [] for name, type_, lines in _list: if type_: lst.append(self.parameterTypesListEntryTemplate.format( **{'Name': name, 'Type': type_, 'Description': html_uencode('\n'.join(lines)), })) else: lst.append(self.parametersListEntryTemplate.format( **{'Name': name, 'Description': html_uencode('\n'.join(lines)), })) return ''.join(lst)
def __genSeeListSection(self, _list, template): """ Private method to generate the "see also" list section of a description. @param _list List containing the info for the section. @param template The template to be used for the list. (string) @return The list section. (string) """ lst = [] for seeEntry in _list: seeEntryString = ''.join(seeEntry) lst.append(template % { \ 'Link' : html_uencode(self.__formatCrossReferenceEntry(seeEntryString)), }) return '\n'.join(lst)
def __genParamDescriptionListSection(self, _list, template): """ Private method to generate the list section of a description. @param _list List containing the info for the list section. @param template The template to be used for the list. (string) @return The list section. (string) """ lst = [] for name, lines in _list: lst.append(template % { \ 'Name' : name, 'Description' : html_uencode('\n'.join(lines)), }) return ''.join(lst)
def __genParamDescriptionListSection(self, _list, template): """ Private method to generate the list section of a description. @param _list List containing the info for the list section. @param template The template to be used for the list. (string) @return The list section. (string) """ lst = [] for name, lines in _list: lst.append(template.format( **{'Name': name, 'Description': html_uencode('\n'.join(lines)), })) return ''.join(lst)
def __genDescriptionListSection(self, dictionary, template): """ Private method to generate the list section of a description. @param dictionary Dictionary containing the info for the list section. @param template The template to be used for the list. (string) @return The list section. (string) """ lst = [] keys = sorted(list(dictionary.keys())) for key in keys: lst.append(template.format( **{'Name': key, 'Description': html_uencode('\n'.join(dictionary[key])), })) return ''.join(lst)
def __genSeeListSection(self, _list, template): """ Private method to generate the "see also" list section of a description. @param _list List containing the info for the section. @param template The template to be used for the list. (string) @return The list section. (string) """ lst = [] for seeEntry in _list: seeEntryString = ''.join(seeEntry) lst.append(template.format( **{'Link': html_uencode(self.__formatCrossReferenceEntry( seeEntryString)), })) return '\n'.join(lst)
def __getShortDescription(self, desc): """ Private method to determine the short description of an object. The short description is just the first non empty line of the documentation string. @param desc The documentation string. (string) @return The short description. (string) """ dlist = desc.splitlines() sdlist = [] descfound = 0 for desc in dlist: desc = desc.strip() if desc: descfound = 1 dotpos = desc.find('.') if dotpos == -1: sdlist.append(desc.strip()) else: 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) if dotpos == -1: break if dotpos == -1: sdlist.append(desc.strip()) else: 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: return html_uencode(' '.join(sdlist)) else: return ''
def __formatDescription(self, descr): """ Private method to format the contents of the documentation string. @param descr The contents of the documentation string. (string) @exception TagError A tag doesn't have the correct number of arguments. @return The formated contents of the documentation string. (string) """ if not descr: return "" paragraphs = [] paramList = [] returns = [] exceptionDict = {} signalDict = {} eventDict = {} deprecated = [] authorInfo = [] sinceInfo = [] seeList = [] lastItem = paragraphs inTagSection = False dlist = descr.splitlines() while dlist and not dlist[0]: del dlist[0] for ditem in dlist: ditem = self.__processInlineTags(ditem) desc = ditem.strip() if desc: if desc.startswith("@param") or desc.startswith("@keyparam"): inTagSection = True parts = desc.split(None, 2) if len(parts) < 2: raise TagError, "Wrong format in %s line.\n" % parts[0] paramName = parts[1] if parts[0] == "@keyparam": paramName += '=' try: paramList.append([paramName, [parts[2]]]) except IndexError: paramList.append([paramName, []]) lastItem = paramList[-1][1] elif desc.startswith("@return"): inTagSection = True parts = desc.split(None, 1) if len(parts) < 2: raise TagError, "Wrong format in %s line.\n" % parts[0] returns = [parts[1]] lastItem = returns elif desc.startswith("@exception") or \ desc.startswith("@throws") or \ desc.startswith("@raise"): inTagSection = True parts = desc.split(None, 2) if len(parts) < 2: raise TagError, "Wrong format in %s line.\n" % parts[0] excName = parts[1] try: exceptionDict[excName] = [parts[2]] except IndexError: exceptionDict[excName] = [] lastItem = exceptionDict[excName] elif desc.startswith("@signal"): inTagSection = True m = _signal(desc,0) if m is None: raise TagError, "Wrong format in %s line.\n" % parts[0] signalName = 1 and m.group("SignalName1") \ or m.group("SignalName2") signalDesc = 1 and m.group("SignalDescription1") \ or m.group("SignalDescription2") signalDict[signalName] = [] if signalDesc is not None: signalDict[signalName].append(signalDesc) lastItem = signalDict[signalName] elif desc.startswith("@event"): inTagSection = True m = _event(desc,0) if m is None: raise TagError, "Wrong format in %s line.\n" % parts[0] eventName = 1 and m.group("EventName1") \ or m.group("EventName2") eventDesc = 1 and m.group("EventDescription1") \ or m.group("EventDescription2") eventDict[eventName] = [] if eventDesc is not None: eventDict[eventName].append(eventDesc) lastItem = eventDict[eventName] elif desc.startswith("@deprecated"): inTagSection = True parts = desc.split(None, 1) if len(parts) < 2: raise TagError, "Wrong format in %s line.\n" % parts[0] deprecated = [parts[1]] lastItem = deprecated elif desc.startswith("@author"): inTagSection = True parts = desc.split(None, 1) if len(parts) < 2: raise TagError, "Wrong format in %s line.\n" % parts[0] authorInfo = [parts[1]] lastItem = authorInfo elif desc.startswith("@since"): inTagSection = True parts = desc.split(None, 1) if len(parts) < 2: raise TagError, "Wrong format in %s line.\n" % parts[0] sinceInfo = [parts[1]] lastItem = sinceInfo elif desc.startswith("@see"): inTagSection = True parts = desc.split(None, 1) if len(parts) < 2: raise TagError, "Wrong format in %s line.\n" % parts[0] seeList.append([parts[1]]) lastItem = seeList[-1] elif desc.startswith("@@"): lastItem.append(desc[1:]) elif desc.startswith("@"): tag = desc.split(None, 1)[0] raise TagError, "Unknown tag encountered, %s.\n" % tag else: lastItem.append(ditem) elif not inTagSection: lastItem.append(ditem) if paragraphs: description = self.__genParagraphs(paragraphs) else: description = "" if paramList: parameterSect = self.parametersListTemplate % { \ 'Parameters' : self.__genParamDescriptionListSection(paramList, self.parametersListEntryTemplate) } else: parameterSect = "" if returns: returnSect = self.returnsTemplate % html_uencode('\n'.join(returns)) else: returnSect = "" if exceptionDict: exceptionSect = self.exceptionsListTemplate % { \ 'Exceptions' : self.__genDescriptionListSection(exceptionDict, self.exceptionsListEntryTemplate) } else: exceptionSect = "" if signalDict: signalSect = self.signalsListTemplate % { \ 'Signals' : self.__genDescriptionListSection(signalDict, self.signalsListEntryTemplate) } else: signalSect = "" if eventDict: eventSect = self.eventsListTemplate % { \ 'Events' : self.__genDescriptionListSection(eventDict, self.eventsListEntryTemplate) } else: eventSect = "" if deprecated: deprecatedSect = self.deprecatedTemplate % { \ 'Lines' : html_uencode('\n'.join(deprecated)), } else: deprecatedSect = "" if authorInfo: authorInfoSect = self.authorInfoTemplate % { \ 'Authors' : html_uencode('\n'.join(authorInfo)), } else: authorInfoSect = "" if sinceInfo: sinceInfoSect = self.sinceInfoTemplate % { \ 'Info' : html_uencode(sinceInfo[0]), } else: sinceInfoSect = "" if seeList: seeSect = self.seeListTemplate % { \ 'Links' : self.__genSeeListSection(seeList, self.seeListEntryTemplate), } else: seeSect = '' return "%s%s%s%s%s%s%s%s%s%s" % ( \ deprecatedSect, description, parameterSect, returnSect, exceptionSect, signalSect, eventSect, authorInfoSect, seeSect, sinceInfoSect )
def __formatDescription(self, descr): """ Private method to format the contents of the documentation string. @param descr The contents of the documentation string. (string) @exception TagError A tag doesn't have the correct number of arguments. @return The formated contents of the documentation string. (string) """ if not descr: return "" paragraphs = [] paramList = [] returns = [] exceptionDict = {} signalDict = {} eventDict = {} deprecated = [] authorInfo = [] sinceInfo = [] seeList = [] lastItem = paragraphs inTagSection = False dlist = descr.splitlines() while dlist and not dlist[0]: del dlist[0] for ditem in dlist: ditem = self.__processInlineTags(ditem) desc = ditem.strip() if desc: if desc.startswith(("@param", "@keyparam")): inTagSection = True parts = desc.split(None, 2) if len(parts) < 2: raise TagError("Wrong format in {0} line.\n".format( parts[0])) paramName = parts[1] if parts[0] == "@keyparam": paramName += '=' try: paramList.append([paramName, [parts[2]]]) except IndexError: paramList.append([paramName, []]) lastItem = paramList[-1][1] elif desc.startswith(("@return", "@ireturn")): inTagSection = True parts = desc.split(None, 1) if len(parts) < 2: raise TagError("Wrong format in {0} line.\n".format( parts[0])) returns = [parts[1]] lastItem = returns elif desc.startswith(("@exception", "@throws", "@raise")): inTagSection = True parts = desc.split(None, 2) if len(parts) < 2: raise TagError("Wrong format in {0} line.\n".format( parts[0])) excName = parts[1] try: exceptionDict[excName] = [parts[2]] except IndexError: exceptionDict[excName] = [] lastItem = exceptionDict[excName] elif desc.startswith("@signal"): inTagSection = True m = _signal(desc, 0) if m is None: raise TagError("Wrong format in @signal line.\n") signalName = 1 and m.group("SignalName1") \ or m.group("SignalName2") signalDesc = 1 and m.group("SignalDescription1") \ or m.group("SignalDescription2") signalDict[signalName] = [] if signalDesc is not None: signalDict[signalName].append(signalDesc) lastItem = signalDict[signalName] elif desc.startswith("@event"): inTagSection = True 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") \ or m.group("EventDescription2") eventDict[eventName] = [] if eventDesc is not None: eventDict[eventName].append(eventDesc) lastItem = eventDict[eventName] elif desc.startswith("@deprecated"): inTagSection = True parts = desc.split(None, 1) if len(parts) < 2: raise TagError("Wrong format in {0} line.\n".format( parts[0])) deprecated = [parts[1]] lastItem = deprecated elif desc.startswith("@author"): inTagSection = True parts = desc.split(None, 1) if len(parts) < 2: raise TagError("Wrong format in {0} line.\n".format( parts[0])) authorInfo = [parts[1]] lastItem = authorInfo elif desc.startswith("@since"): inTagSection = True parts = desc.split(None, 1) if len(parts) < 2: raise TagError("Wrong format in {0} line.\n".format( parts[0])) sinceInfo = [parts[1]] lastItem = sinceInfo elif desc.startswith("@see"): inTagSection = True parts = desc.split(None, 1) if len(parts) < 2: raise TagError("Wrong format in {0} line.\n".format( parts[0])) seeList.append([parts[1]]) lastItem = seeList[-1] elif desc.startswith("@@"): lastItem.append(desc[1:]) elif desc.startswith("@"): tag = desc.split(None, 1)[0] raise TagError( "Unknown tag encountered, {0}.\n".format(tag)) else: lastItem.append(ditem) elif not inTagSection: lastItem.append(ditem) if paragraphs: description = self.__genParagraphs(paragraphs) else: description = "" if paramList: parameterSect = self.parametersListTemplate.format( **{ 'Parameters': self.__genParamDescriptionListSection( paramList, self.parametersListEntryTemplate) }) else: parameterSect = "" if returns: returnSect = self.returnsTemplate.format( html_uencode('\n'.join(returns))) else: returnSect = "" if exceptionDict: exceptionSect = self.exceptionsListTemplate.format( **{ 'Exceptions': self.__genDescriptionListSection( exceptionDict, self.exceptionsListEntryTemplate) }) else: exceptionSect = "" if signalDict: signalSect = self.signalsListTemplate.format( **{ 'Signals': self.__genDescriptionListSection( signalDict, self.signalsListEntryTemplate) }) else: signalSect = "" if eventDict: eventSect = self.eventsListTemplate.format( **{ 'Events': self.__genDescriptionListSection( eventDict, self.eventsListEntryTemplate) }) else: eventSect = "" if deprecated: deprecatedSect = self.deprecatedTemplate.format( **{'Lines': html_uencode('\n'.join(deprecated))}) else: deprecatedSect = "" if authorInfo: authorInfoSect = self.authorInfoTemplate.format( **{'Authors': html_uencode('\n'.join(authorInfo))}) else: authorInfoSect = "" if sinceInfo: sinceInfoSect = self.sinceInfoTemplate.format( **{'Info': html_uencode(sinceInfo[0])}) else: sinceInfoSect = "" if seeList: seeSect = self.seeListTemplate.format( **{ 'Links': self.__genSeeListSection(seeList, self.seeListEntryTemplate) }) else: seeSect = '' return "{0}{1}{2}{3}{4}{5}{6}{7}{8}{9}".format( deprecatedSect, description, parameterSect, returnSect, exceptionSect, signalSect, eventSect, authorInfoSect, seeSect, sinceInfoSect)
def __formatDescription(self, descr): """ Private method to format the contents of the documentation string. @param descr The contents of the documentation string. (string) @exception TagError A tag doesn't have the correct number of arguments. @return The formated contents of the documentation string. (string) """ if not descr: return "" paragraphs = [] paramList = [] returns = [] returnTypes = [] exceptionDict = {} signalDict = {} eventDict = {} deprecated = [] authorInfo = [] sinceInfo = [] seeList = [] lastItem = paragraphs inTagSection = False dlist = descr.splitlines() while dlist and not dlist[0]: del dlist[0] lastTag = "" for ditem in dlist: ditem = self.__processInlineTags(ditem) desc = ditem.strip() if desc: if desc.startswith(("@param", "@keyparam")): inTagSection = True parts = desc.split(None, 2) lastTag = parts[0] if len(parts) < 2: raise TagError( "Wrong format in {0} line.\n".format(parts[0])) paramName = parts[1] if parts[0] == "@keyparam": paramName += '=' try: paramList.append([paramName, "", [parts[2]]]) except IndexError: paramList.append([paramName, "", []]) lastItem = paramList[-1][2] elif desc.startswith("@type"): if lastTag not in ["@param", "@keyparam"]: raise TagError( "{0} line must be preceded by a parameter line\n" .format(parts[0])) inTagSection = True parts = desc.split(None, 1) lastTag = parts[0] if len(parts) < 2: raise TagError( "Wrong format in {0} line.\n".format(parts[0])) paramList[-1][1] = parts[1] elif desc.startswith("@ptype"): inTagSection = True parts = desc.split(None, 2) lastTag = parts[0] if len(parts) < 3: raise TagError( "Wrong format in {0} line.\n".format(parts[0])) param, type_ = parts[1:] for index in range(len(paramList)): if paramList[index][0] == param: paramList[index][1] = type_ break else: raise TagError( "Unknow parameter name '{0}' in {1} line.\n" .format(param, parts[0])) elif desc.startswith(("@return", "@ireturn")): inTagSection = True parts = desc.split(None, 1) lastTag = parts[0] if len(parts) < 2: raise TagError( "Wrong format in {0} line.\n".format(parts[0])) returns = [parts[1]] lastItem = returns elif desc.startswith("@rtype"): inTagSection = True parts = desc.split(None, 1) lastTag = parts[0] if len(parts) < 2: raise TagError( "Wrong format in {0} line.\n".format(parts[0])) returnTypes = [parts[1]] lastItem = returnTypes elif desc.startswith(("@exception", "@throws", "@raise")): inTagSection = True parts = desc.split(None, 2) lastTag = parts[0] if len(parts) < 2: raise TagError( "Wrong format in {0} line.\n".format(parts[0])) excName = parts[1] try: exceptionDict[excName] = [parts[2]] except IndexError: exceptionDict[excName] = [] lastItem = exceptionDict[excName] elif desc.startswith("@signal"): inTagSection = True lastTag = desc.split(None, 1)[0] m = _signal(desc, 0) if m is None: raise TagError("Wrong format in @signal line.\n") signalName = 1 and m.group("SignalName1") \ or m.group("SignalName2") signalDesc = 1 and m.group("SignalDescription1") \ or m.group("SignalDescription2") signalDict[signalName] = [] if signalDesc is not None: signalDict[signalName].append(signalDesc) lastItem = signalDict[signalName] elif desc.startswith("@event"): inTagSection = True lastTag = desc.split(None, 1)[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") \ or m.group("EventDescription2") eventDict[eventName] = [] if eventDesc is not None: eventDict[eventName].append(eventDesc) lastItem = eventDict[eventName] elif desc.startswith("@deprecated"): inTagSection = True parts = desc.split(None, 1) lastTag = parts[0] if len(parts) < 2: raise TagError( "Wrong format in {0} line.\n".format(parts[0])) deprecated = [parts[1]] lastItem = deprecated elif desc.startswith("@author"): inTagSection = True parts = desc.split(None, 1) lastTag = parts[0] if len(parts) < 2: raise TagError( "Wrong format in {0} line.\n".format(parts[0])) authorInfo = [parts[1]] lastItem = authorInfo elif desc.startswith("@since"): inTagSection = True parts = desc.split(None, 1) lastTag = parts[0] if len(parts) < 2: raise TagError( "Wrong format in {0} line.\n".format(parts[0])) sinceInfo = [parts[1]] lastItem = sinceInfo elif desc.startswith("@see"): inTagSection = True parts = desc.split(None, 1) lastTag = parts[0] if len(parts) < 2: raise TagError( "Wrong format in {0} line.\n".format(parts[0])) seeList.append([parts[1]]) lastItem = seeList[-1] elif desc.startswith("@@"): lastItem.append(desc[1:]) elif desc.startswith("@"): tag = desc.split(None, 1)[0] raise TagError( "Unknown tag encountered, {0}.\n".format(tag)) else: lastItem.append(ditem) elif not inTagSection: lastItem.append(ditem) if paragraphs: description = self.__genParagraphs(paragraphs) else: description = "" if paramList: parameterSect = self.parametersListTemplate.format( **{'Parameters': self.__genParamDescriptionListSection( paramList)}) else: parameterSect = "" if returns: returnSect = self.returnsTemplate.format( html_uencode('\n'.join(returns))) else: returnSect = "" if returnTypes: returnTypesSect = self.returnTypesTemplate.format( html_uencode('\n'.join(returnTypes))) else: returnTypesSect = "" if exceptionDict: exceptionSect = self.exceptionsListTemplate.format( **{'Exceptions': self.__genDescriptionListSection( exceptionDict, self.exceptionsListEntryTemplate)}) else: exceptionSect = "" if signalDict: signalSect = self.signalsListTemplate.format( **{'Signals': self.__genDescriptionListSection( signalDict, self.signalsListEntryTemplate)}) else: signalSect = "" if eventDict: eventSect = self.eventsListTemplate.format( **{'Events': self.__genDescriptionListSection( eventDict, self.eventsListEntryTemplate)}) else: eventSect = "" if deprecated: deprecatedSect = self.deprecatedTemplate.format( **{'Lines': html_uencode('\n'.join(deprecated))}) else: deprecatedSect = "" if authorInfo: authorInfoSect = self.authorInfoTemplate.format( **{'Authors': html_uencode('\n'.join(authorInfo))}) else: authorInfoSect = "" if sinceInfo: sinceInfoSect = self.sinceInfoTemplate.format( **{'Info': html_uencode(sinceInfo[0])}) else: sinceInfoSect = "" if seeList: seeSect = self.seeListTemplate.format( **{'Links': self.__genSeeListSection( seeList, self.seeListEntryTemplate)}) else: seeSect = '' return "{0}{1}{2}{3}{4}{5}{6}{7}{8}{9}{10}".format( deprecatedSect, description, parameterSect, returnSect, returnTypesSect, exceptionSect, signalSect, eventSect, authorInfoSect, seeSect, sinceInfoSect, )