--- a/src/eric7/DocumentationTools/ModuleDocumentor.py Wed Jul 13 11:16:20 2022 +0200
+++ b/src/eric7/DocumentationTools/ModuleDocumentor.py Wed Jul 13 14:55:47 2022 +0200
@@ -33,7 +33,9 @@
[a-zA-Z_] \w*
)
[ \t]+ (?P<SignalDescription2> .*)
- """, re.VERBOSE | re.DOTALL | re.MULTILINE).search
+ """,
+ re.VERBOSE | re.DOTALL | re.MULTILINE,
+).search
_event = re.compile(
r"""
@@ -48,13 +50,16 @@
[a-zA-Z_] \w*
)
[ \t]+ (?P<EventDescription2> .*)
- """, re.VERBOSE | re.DOTALL | re.MULTILINE).search
+ """,
+ re.VERBOSE | re.DOTALL | re.MULTILINE,
+).search
class TagError(Exception):
"""
Exception class raised, if an invalid documentation tag was found.
"""
+
pass
@@ -62,78 +67,77 @@
"""
Class implementing the builtin documentation generator.
"""
+
def __init__(self, module):
"""
Constructor
-
+
@param module information of the parsed Python file
@type str
"""
self.module = module
self.empty = True
-
+
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 determine, if the module contains any classes or
functions.
-
+
@return Flag indicating an empty module (i.e. __init__.py without
any contents)
"""
return self.empty
-
+
def name(self):
"""
Public method used to get the module name.
-
+
@return The name of the module. (string)
"""
return self.module.name
-
+
def description(self):
"""
Public method used to get the description of the module.
-
+
@return The description of the module. (string)
"""
return self.__formatDescription(self.module.description)
-
+
def shortDescription(self):
"""
Public method used to get the short description of the module.
-
+
The short description is just the first line of the modules
description.
-
+
@return The short description of the module. (string)
"""
return self.__getShortDescription(self.module.description)
-
+
def genDocument(self):
"""
Public method to generate the source code documentation.
-
+
@return The source code documentation. (string)
"""
doc = (
- TemplatesListsStyleCSS.headerTemplate.format(
- **{'Title': self.module.name}
- ) +
- self.__genModuleSection() +
- TemplatesListsStyleCSS.footerTemplate
+ TemplatesListsStyleCSS.headerTemplate.format(**{"Title": self.module.name})
+ + self.__genModuleSection()
+ + TemplatesListsStyleCSS.footerTemplate
)
self.generated = True
return doc
-
+
def __genModuleSection(self):
"""
Private method to generate the body of the document.
-
+
@return The body of the document. (string)
"""
globalsList = self.__genGlobalsListSection()
@@ -143,46 +147,50 @@
if self.module.type == RB_SOURCE:
rbModulesList = self.__genRbModulesListSection()
modBody = TemplatesListsStyleCSS.rbFileTemplate.format(
- **{'Module': self.module.name,
- 'ModuleDescription':
- self.__formatDescription(self.module.description),
- 'GlobalsList': globalsList,
- 'ClassList': classList,
- 'RbModulesList': rbModulesList,
- 'FunctionList': functionList,
- })
+ **{
+ "Module": self.module.name,
+ "ModuleDescription": self.__formatDescription(
+ self.module.description
+ ),
+ "GlobalsList": globalsList,
+ "ClassList": classList,
+ "RbModulesList": rbModulesList,
+ "FunctionList": functionList,
+ }
+ )
else:
modBody = TemplatesListsStyleCSS.moduleTemplate.format(
- **{'Module': self.module.name,
- 'ModuleDescription':
- self.__formatDescription(self.module.description),
- 'GlobalsList': globalsList,
- 'ClassList': classList,
- 'FunctionList': functionList,
- })
+ **{
+ "Module": self.module.name,
+ "ModuleDescription": self.__formatDescription(
+ self.module.description
+ ),
+ "GlobalsList": globalsList,
+ "ClassList": classList,
+ "FunctionList": functionList,
+ }
+ )
except TagError as e:
- sys.stderr.write(
- "Error processing {0}.\n".format(self.module.file))
+ sys.stderr.write("Error processing {0}.\n".format(self.module.file))
sys.stderr.write(
- "Error in tags of description of module {0}.\n".format(
- self.module.name))
+ "Error in tags of description of module {0}.\n".format(self.module.name)
+ )
sys.stderr.write("{0}\n".format(e))
return ""
-
+
classesSection = self.__genClassesSection()
functionsSection = self.__genFunctionsSection()
rbModulesSection = (
- self.__genRbModulesSection()
- if self.module.type == RB_SOURCE else
- ""
+ self.__genRbModulesSection() if self.module.type == RB_SOURCE else ""
)
return "{0}{1}{2}{3}".format(
- modBody, classesSection, rbModulesSection, functionsSection)
-
+ modBody, classesSection, rbModulesSection, functionsSection
+ )
+
def __genListSection(self, names, sectionDict, kwSuffix=""):
"""
Private method to generate a list section of the document.
-
+
@param names The names to appear in the list. (list of strings)
@param sectionDict dictionary containing all relevant information
(dict)
@@ -191,46 +199,58 @@
"""
lst = []
for name in names:
- lst.append(TemplatesListsStyleCSS.listEntryTemplate.format(
- **{'Link': "{0}".format(name),
- 'Name': sectionDict[name].name,
- 'Description':
- self.__getShortDescription(sectionDict[name].description),
- 'Deprecated':
- self.__checkDeprecated(sectionDict[name].description) and
- TemplatesListsStyleCSS.listEntryDeprecatedTemplate or "",
- }))
- n = ("{0} ({1})".format(name, kwSuffix) if kwSuffix
- else "{0}".format(name))
+ lst.append(
+ TemplatesListsStyleCSS.listEntryTemplate.format(
+ **{
+ "Link": "{0}".format(name),
+ "Name": sectionDict[name].name,
+ "Description": self.__getShortDescription(
+ sectionDict[name].description
+ ),
+ "Deprecated": self.__checkDeprecated(
+ sectionDict[name].description
+ )
+ and TemplatesListsStyleCSS.listEntryDeprecatedTemplate
+ or "",
+ }
+ )
+ )
+ n = "{0} ({1})".format(name, kwSuffix) if kwSuffix else "{0}".format(name)
self.keywords.append((n, "#{0}".format(name)))
- return ''.join(lst)
-
+ return "".join(lst)
+
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)
@return The globals list section. (string)
"""
attrNames = []
scope = class_ if class_ is not None else self.module
- attrNames = sorted(attr for attr in scope.globals.keys()
- if not scope.globals[attr].isSignal)
+ attrNames = sorted(
+ attr for attr in scope.globals.keys() if not scope.globals[attr].isSignal
+ )
s = (
- ''.join(
- [TemplatesListsStyleCSS.listEntrySimpleTemplate
- .format(**{'Name': name}) for name in attrNames])
- if attrNames else
- TemplatesListsStyleCSS.listEntryNoneTemplate
+ "".join(
+ [
+ TemplatesListsStyleCSS.listEntrySimpleTemplate.format(
+ **{"Name": name}
+ )
+ for name in attrNames
+ ]
+ )
+ if attrNames
+ else TemplatesListsStyleCSS.listEntryNoneTemplate
)
- return TemplatesListsStyleCSS.listTemplate.format(**{'Entries': s})
-
+ return TemplatesListsStyleCSS.listTemplate.format(**{"Entries": s})
+
def __genClassListSection(self):
"""
Private method to generate the section listing all classes of the
module.
-
+
@return The classes list section. (string)
"""
names = sorted(self.module.classes.keys())
@@ -239,13 +259,13 @@
s = self.__genListSection(names, self.module.classes)
else:
s = TemplatesListsStyleCSS.listEntryNoneTemplate
- return TemplatesListsStyleCSS.listTemplate.format(**{'Entries': s})
-
+ return TemplatesListsStyleCSS.listTemplate.format(**{"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(self.module.modules.keys())
@@ -254,13 +274,13 @@
s = self.__genListSection(names, self.module.modules)
else:
s = TemplatesListsStyleCSS.listEntryNoneTemplate
- return TemplatesListsStyleCSS.listTemplate.format(**{'Entries': s})
-
+ return TemplatesListsStyleCSS.listTemplate.format(**{"Entries": s})
+
def __genFunctionListSection(self):
"""
Private method to generate the section listing all functions of the
module.
-
+
@return The functions list section. (string)
"""
names = sorted(self.module.functions.keys())
@@ -269,13 +289,13 @@
s = self.__genListSection(names, self.module.functions)
else:
s = TemplatesListsStyleCSS.listEntryNoneTemplate
- return TemplatesListsStyleCSS.listTemplate.format(**{'Entries': s})
-
+ return TemplatesListsStyleCSS.listTemplate.format(**{"Entries": s})
+
def __genClassesSection(self):
"""
Private method to generate the document section with details about
classes.
-
+
@return The classes details section. (string)
"""
classNames = sorted(self.module.classes.keys())
@@ -283,48 +303,55 @@
for className in classNames:
_class = self.module.classes[className]
supers = _class.super
- supers = ', '.join(supers) if len(supers) > 0 else "None"
-
+ supers = ", ".join(supers) if len(supers) > 0 else "None"
+
globalsList = self.__genGlobalsListSection(_class)
classMethList, classMethBodies = self.__genMethodSection(
- _class, className, Function.Class)
+ _class, className, Function.Class
+ )
methList, methBodies = self.__genMethodSection(
- _class, className, Function.General)
+ _class, className, Function.General
+ )
staticMethList, staticMethBodies = self.__genMethodSection(
- _class, className, Function.Static)
-
+ _class, className, Function.Static
+ )
+
try:
clsBody = TemplatesListsStyleCSS.classTemplate.format(
- **{'Anchor': className,
- 'Class': _class.name,
- 'ClassSuper': supers,
- 'ClassDescription':
- self.__formatDescription(_class.description),
- 'GlobalsList': globalsList,
- 'ClassMethodList': classMethList,
- 'MethodList': methList,
- 'StaticMethodList': staticMethList,
- 'MethodDetails':
- classMethBodies + methBodies + staticMethBodies,
- })
+ **{
+ "Anchor": className,
+ "Class": _class.name,
+ "ClassSuper": supers,
+ "ClassDescription": self.__formatDescription(
+ _class.description
+ ),
+ "GlobalsList": globalsList,
+ "ClassMethodList": classMethList,
+ "MethodList": methList,
+ "StaticMethodList": staticMethList,
+ "MethodDetails": classMethBodies
+ + methBodies
+ + staticMethBodies,
+ }
+ )
except TagError as e:
- sys.stderr.write(
- "Error processing {0}.\n".format(self.module.file))
+ sys.stderr.write("Error processing {0}.\n".format(self.module.file))
sys.stderr.write(
- "Error in tags of description of class {0}.\n".format(
- className))
+ "Error in tags of description of class {0}.\n".format(className)
+ )
sys.stderr.write("{0}\n".format(e))
clsBody = ""
-
+
classes.append(clsBody)
-
- return ''.join(classes)
-
- def __genMethodsListSection(self, names, sectionDict, className, clsName,
- includeInit=True):
+
+ return "".join(classes)
+
+ def __genMethodsListSection(
+ self, names, sectionDict, className, clsName, includeInit=True
+ ):
"""
Private method to generate the methods list section of a class.
-
+
@param names names to appear in the list (list of strings)
@param sectionDict dictionary containing all relevant information
(dict)
@@ -337,38 +364,55 @@
lst = []
if includeInit:
with contextlib.suppress(KeyError):
- lst.append(TemplatesListsStyleCSS.listEntryTemplate.format(
- **{'Link': "{0}.{1}".format(className, '__init__'),
- 'Name': clsName,
- 'Description': self.__getShortDescription(
- sectionDict['__init__'].description),
- 'Deprecated': self.__checkDeprecated(
- sectionDict['__init__'].description) and
- TemplatesListsStyleCSS.listEntryDeprecatedTemplate or
- "",
- }))
+ lst.append(
+ TemplatesListsStyleCSS.listEntryTemplate.format(
+ **{
+ "Link": "{0}.{1}".format(className, "__init__"),
+ "Name": clsName,
+ "Description": self.__getShortDescription(
+ sectionDict["__init__"].description
+ ),
+ "Deprecated": self.__checkDeprecated(
+ sectionDict["__init__"].description
+ )
+ and TemplatesListsStyleCSS.listEntryDeprecatedTemplate
+ or "",
+ }
+ )
+ )
self.keywords.append(
- ("{0} (Constructor)".format(className),
- "#{0}.{1}".format(className, '__init__')))
-
+ (
+ "{0} (Constructor)".format(className),
+ "#{0}.{1}".format(className, "__init__"),
+ )
+ )
+
for name in names:
- lst.append(TemplatesListsStyleCSS.listEntryTemplate.format(
- **{'Link': "{0}.{1}".format(className, name),
- 'Name': sectionDict[name].name,
- 'Description':
- self.__getShortDescription(sectionDict[name].description),
- 'Deprecated':
- self.__checkDeprecated(sectionDict[name].description) and
- TemplatesListsStyleCSS.listEntryDeprecatedTemplate or "",
- }))
- self.keywords.append(("{0}.{1}".format(className, name),
- "#{0}.{1}".format(className, name)))
- return ''.join(lst)
-
+ lst.append(
+ TemplatesListsStyleCSS.listEntryTemplate.format(
+ **{
+ "Link": "{0}.{1}".format(className, name),
+ "Name": sectionDict[name].name,
+ "Description": self.__getShortDescription(
+ sectionDict[name].description
+ ),
+ "Deprecated": self.__checkDeprecated(
+ sectionDict[name].description
+ )
+ and TemplatesListsStyleCSS.listEntryDeprecatedTemplate
+ or "",
+ }
+ )
+ )
+ self.keywords.append(
+ ("{0}.{1}".format(className, name), "#{0}.{1}".format(className, name))
+ )
+ return "".join(lst)
+
def __genMethodSection(self, obj, className, modifierFilter):
"""
Private method to generate the method details section.
-
+
@param obj reference to the object being formatted
@param className name of the class containing the method (string)
@param modifierFilter filter value designating the method types
@@ -376,31 +420,34 @@
"""
methList = []
methBodies = []
- methods = sorted(k for k in obj.methods.keys()
- if obj.methods[k].modifier == modifierFilter)
- if '__init__' in methods:
- methods.remove('__init__')
+ methods = sorted(
+ k for k in obj.methods.keys() if obj.methods[k].modifier == modifierFilter
+ )
+ if "__init__" in methods:
+ methods.remove("__init__")
try:
methBody = TemplatesListsStyleCSS.constructorTemplate.format(
- **{'Anchor': className,
- 'Class': obj.name,
- 'Method': '__init__',
- 'MethodDescription':
- self.__formatDescription(
- obj.methods['__init__'].description),
- 'Params':
- ', '.join(obj.methods['__init__'].parameters[1:]),
- })
+ **{
+ "Anchor": className,
+ "Class": obj.name,
+ "Method": "__init__",
+ "MethodDescription": self.__formatDescription(
+ obj.methods["__init__"].description
+ ),
+ "Params": ", ".join(obj.methods["__init__"].parameters[1:]),
+ }
+ )
except TagError as e:
- sys.stderr.write(
- "Error processing {0}.\n".format(self.module.file))
+ sys.stderr.write("Error processing {0}.\n".format(self.module.file))
sys.stderr.write(
"Error in tags of description of method {0}.{1}.\n".format(
- className, '__init__'))
+ className, "__init__"
+ )
+ )
sys.stderr.write("{0}\n".format(e))
methBody = ""
methBodies.append(methBody)
-
+
if modifierFilter == Function.Class:
methodClassifier = " (class method)"
elif modifierFilter == Function.Static:
@@ -410,39 +457,48 @@
for method in methods:
try:
methBody = TemplatesListsStyleCSS.methodTemplate.format(
- **{'Anchor': className,
- 'Class': obj.name,
- 'Method': obj.methods[method].name,
- 'MethodClassifier': methodClassifier,
- 'MethodDescription':
- self.__formatDescription(
- obj.methods[method].description),
- 'Params': ', '.join(obj.methods[method].parameters[1:]),
- })
+ **{
+ "Anchor": className,
+ "Class": obj.name,
+ "Method": obj.methods[method].name,
+ "MethodClassifier": methodClassifier,
+ "MethodDescription": self.__formatDescription(
+ obj.methods[method].description
+ ),
+ "Params": ", ".join(obj.methods[method].parameters[1:]),
+ }
+ )
except TagError as e:
- sys.stderr.write(
- "Error processing {0}.\n".format(self.module.file))
+ sys.stderr.write("Error processing {0}.\n".format(self.module.file))
sys.stderr.write(
"Error in tags of description of method {0}.{1}.\n".format(
- className, method))
+ className, method
+ )
+ )
sys.stderr.write("{0}\n".format(e))
methBody = ""
methBodies.append(methBody)
-
+
methList = self.__genMethodsListSection(
- methods, obj.methods, className, obj.name,
- includeInit=modifierFilter == Function.General)
-
+ methods,
+ obj.methods,
+ className,
+ obj.name,
+ includeInit=modifierFilter == Function.General,
+ )
+
if not methList:
methList = TemplatesListsStyleCSS.listEntryNoneTemplate
- return (TemplatesListsStyleCSS.listTemplate
- .format(**{'Entries': methList}), ''.join(methBodies))
-
+ return (
+ TemplatesListsStyleCSS.listTemplate.format(**{"Entries": methList}),
+ "".join(methBodies),
+ )
+
def __genRbModulesSection(self):
"""
Private method to generate the document section with details about
Ruby modules.
-
+
@return The Ruby modules details section. (string)
"""
rbModulesNames = sorted(self.module.modules.keys())
@@ -451,39 +507,45 @@
rbModule = self.module.modules[rbModuleName]
globalsList = self.__genGlobalsListSection(rbModule)
methList, methBodies = self.__genMethodSection(
- rbModule, rbModuleName, Function.General)
+ rbModule, rbModuleName, Function.General
+ )
classList, classBodies = self.__genRbModulesClassesSection(
- rbModule, rbModuleName)
-
+ rbModule, rbModuleName
+ )
+
try:
rbmBody = TemplatesListsStyleCSS.rbModuleTemplate.format(
- **{'Anchor': rbModuleName,
- 'Module': rbModule.name,
- 'ModuleDescription':
- self.__formatDescription(rbModule.description),
- 'GlobalsList': globalsList,
- 'ClassesList': classList,
- 'ClassesDetails': classBodies,
- 'FunctionsList': methList,
- 'FunctionsDetails': methBodies,
- })
+ **{
+ "Anchor": rbModuleName,
+ "Module": rbModule.name,
+ "ModuleDescription": self.__formatDescription(
+ rbModule.description
+ ),
+ "GlobalsList": globalsList,
+ "ClassesList": classList,
+ "ClassesDetails": classBodies,
+ "FunctionsList": methList,
+ "FunctionsDetails": methBodies,
+ }
+ )
except TagError as e:
- sys.stderr.write(
- "Error processing {0}.\n".format(self.module.file))
+ sys.stderr.write("Error processing {0}.\n".format(self.module.file))
sys.stderr.write(
- "Error in tags of description of Ruby module {0}.\n"
- .format(rbModuleName))
+ "Error in tags of description of Ruby module {0}.\n".format(
+ rbModuleName
+ )
+ )
sys.stderr.write("{0}\n".format(e))
rbmBody = ""
-
+
rbModules.append(rbmBody)
-
- return ''.join(rbModules)
+
+ return "".join(rbModules)
def __genRbModulesClassesSection(self, obj, modName):
"""
Private method to generate the Ruby module classes details section.
-
+
@param obj Reference to the object being formatted.
@param modName Name of the Ruby module containing the classes. (string)
@return The classes list and classes details section.
@@ -494,44 +556,50 @@
for className in classNames:
_class = obj.classes[className]
supers = _class.super
- supers = ', '.join(supers) if len(supers) > 0 else "None"
-
+ supers = ", ".join(supers) if len(supers) > 0 else "None"
+
methList, methBodies = self.__genMethodSection(
- _class, className, Function.General)
-
+ _class, className, Function.General
+ )
+
try:
clsBody = TemplatesListsStyleCSS.rbModulesClassTemplate.format(
- **{'Anchor': className,
- 'Class': _class.name,
- 'ClassSuper': supers,
- 'ClassDescription':
- self.__formatDescription(_class.description),
- 'MethodList': methList,
- 'MethodDetails': methBodies,
- })
+ **{
+ "Anchor": className,
+ "Class": _class.name,
+ "ClassSuper": supers,
+ "ClassDescription": self.__formatDescription(
+ _class.description
+ ),
+ "MethodList": methList,
+ "MethodDetails": methBodies,
+ }
+ )
except TagError as e:
- sys.stderr.write(
- "Error processing {0}.\n".format(self.module.file))
+ sys.stderr.write("Error processing {0}.\n".format(self.module.file))
sys.stderr.write(
- "Error in tags of description of class {0}.\n".format(
- className))
+ "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)
-
+ classNames, obj.classes, modName
+ )
+
if not classesList:
classesList = TemplatesListsStyleCSS.listEntryNoneTemplate
- return (TemplatesListsStyleCSS.listTemplate
- .format(**{'Entries': classesList}), ''.join(classes))
-
+ return (
+ TemplatesListsStyleCSS.listTemplate.format(**{"Entries": classesList}),
+ "".join(classes),
+ )
+
def __genRbModulesClassesListSection(self, names, sectionDict, moduleName):
"""
Private method to generate the classes list section of a Ruby module.
-
+
@param names The names to appear in the list. (list of strings)
@param sectionDict dictionary containing all relevant information
(dict)
@@ -541,24 +609,35 @@
"""
lst = []
for name in names:
- lst.append(TemplatesListsStyleCSS.listEntryTemplate.format(
- **{'Link': "{0}.{1}".format(moduleName, name),
- 'Name': sectionDict[name].name,
- 'Description':
- self.__getShortDescription(sectionDict[name].description),
- 'Deprecated':
- self.__checkDeprecated(sectionDict[name].description) and
- TemplatesListsStyleCSS.listEntryDeprecatedTemplate or "",
- }))
- self.keywords.append(("{0}.{1}".format(moduleName, name),
- "#{0}.{1}".format(moduleName, name)))
- return ''.join(lst)
-
+ lst.append(
+ TemplatesListsStyleCSS.listEntryTemplate.format(
+ **{
+ "Link": "{0}.{1}".format(moduleName, name),
+ "Name": sectionDict[name].name,
+ "Description": self.__getShortDescription(
+ sectionDict[name].description
+ ),
+ "Deprecated": self.__checkDeprecated(
+ sectionDict[name].description
+ )
+ and TemplatesListsStyleCSS.listEntryDeprecatedTemplate
+ or "",
+ }
+ )
+ )
+ self.keywords.append(
+ (
+ "{0}.{1}".format(moduleName, name),
+ "#{0}.{1}".format(moduleName, name),
+ )
+ )
+ return "".join(lst)
+
def __genFunctionsSection(self):
"""
Private method to generate the document section with details about
functions.
-
+
@return The functions details section. (string)
"""
funcBodies = []
@@ -566,33 +645,34 @@
for funcName in funcNames:
try:
funcBody = TemplatesListsStyleCSS.functionTemplate.format(
- **{'Anchor': funcName,
- 'Function': self.module.functions[funcName].name,
- 'FunctionDescription': self.__formatDescription(
- self.module.functions[funcName].description),
- 'Params':
- ', '.join(self.module.functions[funcName].parameters),
- })
+ **{
+ "Anchor": funcName,
+ "Function": self.module.functions[funcName].name,
+ "FunctionDescription": self.__formatDescription(
+ self.module.functions[funcName].description
+ ),
+ "Params": ", ".join(self.module.functions[funcName].parameters),
+ }
+ )
except TagError as e:
- sys.stderr.write(
- "Error processing {0}.\n".format(self.module.file))
+ sys.stderr.write("Error processing {0}.\n".format(self.module.file))
sys.stderr.write(
- "Error in tags of description of function {0}.\n".format(
- funcName))
+ "Error in tags of description of function {0}.\n".format(funcName)
+ )
sys.stderr.write("{0}\n".format(e))
funcBody = ""
-
+
funcBodies.append(funcBody)
-
- return ''.join(funcBodies)
-
+
+ return "".join(funcBodies)
+
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)
"""
@@ -603,37 +683,34 @@
desc = desc.strip()
if desc:
descfound = 1
- dotpos = desc.find('.')
+ 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())
- break # break if a '.' is found
+ sdlist.append(desc[: dotpos + 1].strip())
+ break # break if a '.' is found
else:
if descfound:
- break # break if an empty line is found
+ break # break if an empty line is found
if sdlist:
- return html_uencode(' '.join(sdlist))
+ return html_uencode(" ".join(sdlist))
else:
- return ''
-
+ return ""
+
def __checkDeprecated(self, descr):
"""
Private method to check, if the object to be documented contains a
deprecated flag.
-
+
@param descr documentation string (string)
@return flag indicating the deprecation status (boolean)
"""
@@ -643,15 +720,15 @@
if desc.startswith("@deprecated"):
return True
return False
-
+
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)
"""
@@ -659,23 +736,29 @@
linelist = []
for line in lines:
if line.strip():
- if line == '.':
+ if line == ".":
linelist.append("")
else:
linelist.append(html_uencode(line))
else:
- lst.append(TemplatesListsStyleCSS.paragraphTemplate.format(
- **{'Lines': '\n'.join(linelist)}))
+ lst.append(
+ TemplatesListsStyleCSS.paragraphTemplate.format(
+ **{"Lines": "\n".join(linelist)}
+ )
+ )
linelist = []
if linelist:
- lst.append(TemplatesListsStyleCSS.paragraphTemplate.format(
- **{'Lines': '\n'.join(linelist)}))
- return ''.join(lst)
-
+ lst.append(
+ TemplatesListsStyleCSS.paragraphTemplate.format(
+ **{"Lines": "\n".join(linelist)}
+ )
+ )
+ 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)
@@ -684,16 +767,20 @@
lst = []
keys = sorted(dictionary.keys())
for key in keys:
- lst.append(template.format(
- **{'Name': key,
- 'Description': html_uencode('\n'.join(dictionary[key])),
- }))
- return ''.join(lst)
-
+ lst.append(
+ template.format(
+ **{
+ "Name": key,
+ "Description": html_uencode("\n".join(dictionary[key])),
+ }
+ )
+ )
+ 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)
@@ -702,36 +789,37 @@
for name, type_, lines in _list:
if type_:
lst.append(
- TemplatesListsStyleCSS.parameterTypesListEntryTemplate
- .format(
- **{'Name': name,
- 'Type': type_,
- 'Description': html_uencode('\n'.join(lines)),
- }
+ TemplatesListsStyleCSS.parameterTypesListEntryTemplate.format(
+ **{
+ "Name": name,
+ "Type": type_,
+ "Description": html_uencode("\n".join(lines)),
+ }
)
)
else:
lst.append(
TemplatesListsStyleCSS.parametersListEntryTemplate.format(
- **{'Name': name,
- 'Description': html_uencode('\n'.join(lines)),
- }
+ **{
+ "Name": name,
+ "Description": html_uencode("\n".join(lines)),
+ }
)
)
- return ''.join(lst)
-
+ return "".join(lst)
+
def __formatCrossReferenceEntry(self, entry):
"""
Private method to format a cross reference entry.
-
+
This cross reference entry looks like "package.module#member label".
-
+
@param entry the entry to be formatted (string)
@return formatted entry (string)
"""
if entry.startswith('"'):
return entry
- elif entry.startswith('<'):
+ elif entry.startswith("<"):
entry = entry[3:]
else:
try:
@@ -740,73 +828,78 @@
reference = entry
label = entry
try:
- path, anchor = reference.split('#', 1)
+ path, anchor = reference.split("#", 1)
except ValueError:
path = reference
- anchor = ''
- reference = path and "{0}.html".format(path) or ''
+ anchor = ""
+ reference = path and "{0}.html".format(path) or ""
if anchor:
reference = "{0}#{1}".format(reference, anchor)
entry = 'href="{0}">{1}</a>'.format(reference, label)
-
- return TemplatesListsStyleCSS.seeLinkTemplate.format(**{'Link': entry})
-
+
+ return TemplatesListsStyleCSS.seeLinkTemplate.format(**{"Link": entry})
+
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)
-
+ seeEntryString = "".join(seeEntry)
+ lst.append(
+ template.format(
+ **{
+ "Link": html_uencode(
+ self.__formatCrossReferenceEntry(seeEntryString)
+ ),
+ }
+ )
+ )
+ return "\n".join(lst)
+
def __processInlineTags(self, desc):
"""
Private method to process inline tags.
-
+
@param desc One line of the description (string)
@return processed line with inline tags expanded (string)
@exception TagError raised to indicate an invalid tag
"""
- start = desc.find('{@')
+ start = desc.find("{@")
while start != -1:
- stop = desc.find('}', start + 2)
+ stop = desc.find("}", start + 2)
if stop == -1:
raise TagError("Unterminated inline tag.\n{0}".format(desc))
-
- tagText = desc[start + 1:stop]
- if tagText.startswith('@link'):
+
+ tagText = desc[start + 1 : stop]
+ if tagText.startswith("@link"):
parts = tagText.split(None, 1)
if len(parts) < 2:
raise TagError(
- "Wrong format in inline tag {0}.\n{1}".format(
- parts[0], desc))
-
+ "Wrong format in inline tag {0}.\n{1}".format(parts[0], desc)
+ )
+
formattedTag = self.__formatCrossReferenceEntry(parts[1])
desc = desc.replace("{{{0}}}".format(tagText), formattedTag)
else:
tag = tagText.split(None, 1)[0]
raise TagError(
- "Unknown inline tag encountered, {0}.\n{1}".format(
- tag, desc))
-
- start = desc.find('{@')
-
+ "Unknown inline tag encountered, {0}.\n{1}".format(tag, desc)
+ )
+
+ start = desc.find("{@")
+
return desc
-
+
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.
@@ -814,7 +907,7 @@
"""
if not descr:
return ""
-
+
paragraphs = []
paramList = []
returns = []
@@ -830,7 +923,7 @@
seeList = []
lastItem = paragraphs
inTagSection = False
-
+
dlist = descr.splitlines()
while dlist and not dlist[0]:
del dlist[0]
@@ -842,8 +935,7 @@
if buffer:
if desc.startswith("@"):
buffer = ""
- raise TagError(
- "Wrong format in {0} line.\n".format(lastTag))
+ raise TagError("Wrong format in {0} line.\n".format(lastTag))
else:
desc = buffer + desc
if desc:
@@ -852,11 +944,10 @@
parts = desc.split(None, 2)
lastTag = parts[0]
if len(parts) < 2:
- raise TagError(
- "Wrong format in {0} line.\n".format(parts[0]))
+ raise TagError("Wrong format in {0} line.\n".format(parts[0]))
paramName = parts[1]
if parts[0] == "@keyparam":
- paramName += '='
+ paramName += "="
try:
paramList.append([paramName, "", [parts[2]]])
except IndexError:
@@ -866,21 +957,21 @@
parts = desc.split(None, 1)
if lastTag not in ["@param", "@keyparam"]:
raise TagError(
- "{0} line must be preceded by a parameter line\n"
- .format(parts[0]))
+ "{0} line must be preceded by a parameter line\n".format(
+ parts[0]
+ )
+ )
inTagSection = True
lastTag = parts[0]
if len(parts) < 2:
- raise TagError(
- "Wrong format in {0} line.\n".format(parts[0]))
+ 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]))
+ 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:
@@ -888,28 +979,30 @@
break
else:
raise TagError(
- "Unknow parameter name '{0}' in {1} line.\n"
- .format(param, parts[0]))
+ "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]))
+ raise TagError("Wrong format in {0} line.\n".format(parts[0]))
returns = [parts[1]]
lastItem = returns
elif desc.startswith("@rtype"):
parts = desc.split(None, 1)
if lastTag not in ["@return", "@ireturn"]:
raise TagError(
- "{0} line must be preceded by a @return line\n"
- .format(parts[0]))
+ "{0} line must be preceded by a @return line\n".format(
+ parts[0]
+ )
+ )
inTagSection = True
lastTag = parts[0]
if len(parts) < 2:
- raise TagError(
- "Wrong format in {0} line.\n".format(parts[0]))
+ raise TagError("Wrong format in {0} line.\n".format(parts[0]))
returnTypes = [parts[1]]
lastItem = returnTypes
elif desc.startswith("@yield"):
@@ -917,21 +1010,21 @@
parts = desc.split(None, 1)
lastTag = parts[0]
if len(parts) < 2:
- raise TagError(
- "Wrong format in {0} line.\n".format(parts[0]))
+ raise TagError("Wrong format in {0} line.\n".format(parts[0]))
yields = [parts[1]]
lastItem = yields
elif desc.startswith("@ytype"):
parts = desc.split(None, 1)
if lastTag != "@yield":
raise TagError(
- "{0} line must be preceded by a @yield line\n"
- .format(parts[0]))
+ "{0} line must be preceded by a @yield line\n".format(
+ parts[0]
+ )
+ )
inTagSection = True
lastTag = parts[0]
if len(parts) < 2:
- raise TagError(
- "Wrong format in {0} line.\n".format(parts[0]))
+ raise TagError("Wrong format in {0} line.\n".format(parts[0]))
yieldTypes = [parts[1]]
lastItem = yieldTypes
elif desc.startswith(("@exception", "@throws", "@raise")):
@@ -939,8 +1032,7 @@
parts = desc.split(None, 2)
lastTag = parts[0]
if len(parts) < 2:
- raise TagError(
- "Wrong format in {0} line.\n".format(parts[0]))
+ raise TagError("Wrong format in {0} line.\n".format(parts[0]))
excName = parts[1]
try:
exceptionDict[excName] = [parts[2]]
@@ -955,12 +1047,9 @@
buffer = desc
else:
buffer = ""
- signalName = (
- m.group("SignalName1") or m.group("SignalName2")
- )
- signalDesc = (
- m.group("SignalDescription1") or
- m.group("SignalDescription2")
+ signalName = m.group("SignalName1") or m.group("SignalName2")
+ signalDesc = m.group("SignalDescription1") or m.group(
+ "SignalDescription2"
)
signalDict[signalName] = []
if signalDesc is not None:
@@ -974,12 +1063,9 @@
buffer = desc
else:
buffer = ""
- eventName = (
- m.group("EventName1") or m.group("EventName2")
- )
- eventDesc = (
- m.group("EventDescription1") or
- m.group("EventDescription2")
+ eventName = m.group("EventName1") or m.group("EventName2")
+ eventDesc = m.group("EventDescription1") or m.group(
+ "EventDescription2"
)
eventDict[eventName] = []
if eventDesc is not None:
@@ -990,8 +1076,7 @@
parts = desc.split(None, 1)
lastTag = parts[0]
if len(parts) < 2:
- raise TagError(
- "Wrong format in {0} line.\n".format(parts[0]))
+ raise TagError("Wrong format in {0} line.\n".format(parts[0]))
deprecated = [parts[1]]
lastItem = deprecated
elif desc.startswith("@author"):
@@ -999,8 +1084,7 @@
parts = desc.split(None, 1)
lastTag = parts[0]
if len(parts) < 2:
- raise TagError(
- "Wrong format in {0} line.\n".format(parts[0]))
+ raise TagError("Wrong format in {0} line.\n".format(parts[0]))
authorInfo = [parts[1]]
lastItem = authorInfo
elif desc.startswith("@since"):
@@ -1008,8 +1092,7 @@
parts = desc.split(None, 1)
lastTag = parts[0]
if len(parts) < 2:
- raise TagError(
- "Wrong format in {0} line.\n".format(parts[0]))
+ raise TagError("Wrong format in {0} line.\n".format(parts[0]))
sinceInfo = [parts[1]]
lastItem = sinceInfo
elif desc.startswith("@see"):
@@ -1017,132 +1100,160 @@
parts = desc.split(None, 1)
lastTag = parts[0]
if len(parts) < 2:
- raise TagError(
- "Wrong format in {0} line.\n".format(parts[0]))
+ 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))
+ raise TagError("Unknown tag encountered, {0}.\n".format(tag))
else:
lastItem.append(ditem)
elif not inTagSection:
lastItem.append(ditem)
-
+
description = self.__genParagraphs(paragraphs) if paragraphs else ""
-
+
parameterSect = (
TemplatesListsStyleCSS.parametersListTemplate.format(
- **{'Parameters': self.__genParamDescriptionListSection(
- paramList)})
- if paramList else
- ""
+ **{"Parameters": self.__genParamDescriptionListSection(paramList)}
+ )
+ if paramList
+ else ""
)
-
+
returnSect = (
TemplatesListsStyleCSS.returnsTemplate.format(
- html_uencode('\n'.join(returns)))
- if returns else
- ""
+ html_uencode("\n".join(returns))
+ )
+ if returns
+ else ""
)
-
+
returnTypesSect = (
TemplatesListsStyleCSS.returnTypesTemplate.format(
- html_uencode('\n'.join(returnTypes)))
- if returnTypes else
- ""
+ html_uencode("\n".join(returnTypes))
+ )
+ if returnTypes
+ else ""
)
-
+
yieldSect = (
TemplatesListsStyleCSS.yieldsTemplate.format(
- html_uencode('\n'.join(yields)))
- if yields else
- ""
+ html_uencode("\n".join(yields))
+ )
+ if yields
+ else ""
)
-
+
yieldTypesSect = (
TemplatesListsStyleCSS.yieldTypesTemplate.format(
- html_uencode('\n'.join(yieldTypes)))
- if yieldTypes else
- ""
+ html_uencode("\n".join(yieldTypes))
+ )
+ if yieldTypes
+ else ""
)
-
+
exceptionSect = (
TemplatesListsStyleCSS.exceptionsListTemplate.format(
- **{'Exceptions': self.__genDescriptionListSection(
- exceptionDict,
- TemplatesListsStyleCSS.exceptionsListEntryTemplate)}
+ **{
+ "Exceptions": self.__genDescriptionListSection(
+ exceptionDict,
+ TemplatesListsStyleCSS.exceptionsListEntryTemplate,
+ )
+ }
)
- if exceptionDict else
- ""
+ if exceptionDict
+ else ""
)
-
+
signalSect = (
TemplatesListsStyleCSS.signalsListTemplate.format(
- **{'Signals': self.__genDescriptionListSection(
- signalDict,
- TemplatesListsStyleCSS.signalsListEntryTemplate)}
+ **{
+ "Signals": self.__genDescriptionListSection(
+ signalDict, TemplatesListsStyleCSS.signalsListEntryTemplate
+ )
+ }
)
- if signalDict else
- ""
+ if signalDict
+ else ""
)
-
+
eventSect = (
TemplatesListsStyleCSS.eventsListTemplate.format(
- **{'Events': self.__genDescriptionListSection(
- eventDict,
- TemplatesListsStyleCSS.eventsListEntryTemplate)}
+ **{
+ "Events": self.__genDescriptionListSection(
+ eventDict, TemplatesListsStyleCSS.eventsListEntryTemplate
+ )
+ }
)
- if eventDict else
- ""
+ if eventDict
+ else ""
)
-
+
deprecatedSect = (
TemplatesListsStyleCSS.deprecatedTemplate.format(
- **{'Lines': html_uencode('\n'.join(deprecated))})
- if deprecated else
- ""
+ **{"Lines": html_uencode("\n".join(deprecated))}
+ )
+ if deprecated
+ else ""
)
-
+
authorInfoSect = (
TemplatesListsStyleCSS.authorInfoTemplate.format(
- **{'Authors': html_uencode('\n'.join(authorInfo))})
- if authorInfo else
- ""
+ **{"Authors": html_uencode("\n".join(authorInfo))}
+ )
+ if authorInfo
+ else ""
)
-
+
sinceInfoSect = (
TemplatesListsStyleCSS.sinceInfoTemplate.format(
- **{'Info': html_uencode(sinceInfo[0])})
- if sinceInfo else
- ""
+ **{"Info": html_uencode(sinceInfo[0])}
+ )
+ if sinceInfo
+ else ""
)
-
+
seeSect = (
TemplatesListsStyleCSS.seeListTemplate.format(
- **{'Links': self.__genSeeListSection(
- seeList, TemplatesListsStyleCSS.seeListEntryTemplate)})
- if seeList else
- ''
+ **{
+ "Links": self.__genSeeListSection(
+ seeList, TemplatesListsStyleCSS.seeListEntryTemplate
+ )
+ }
+ )
+ if seeList
+ else ""
)
-
- return "".join([
- deprecatedSect, description, parameterSect, returnSect,
- returnTypesSect, yieldSect, yieldTypesSect, exceptionSect,
- signalSect, eventSect, authorInfoSect, seeSect, sinceInfoSect,
- ])
-
+
+ return "".join(
+ [
+ deprecatedSect,
+ description,
+ parameterSect,
+ returnSect,
+ returnTypesSect,
+ yieldSect,
+ yieldTypesSect,
+ exceptionSect,
+ signalSect,
+ eventSect,
+ authorInfoSect,
+ seeSect,
+ sinceInfoSect,
+ ]
+ )
+
def getQtHelpKeywords(self):
"""
Public method to retrieve the parts for the QtHelp keywords section.
-
+
@return list of tuples containing the name (string) and the ref
(string). The ref is without the filename part.
"""
if not self.generated:
self.genDocument()
-
+
return self.keywords
