--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/eric7/Documentation/Source/eric7.DocumentationTools.ModuleDocumentor.html Mon May 24 11:19:57 2021 +0200 @@ -0,0 +1,832 @@ +<!DOCTYPE html> +<html><head> +<title>eric7.DocumentationTools.ModuleDocumentor</title> +<meta charset="UTF-8"> +<style> +body { + background: #EDECE6; + margin: 0em 1em 10em 1em; + color: black; +} + +h1 { color: white; background: #85774A; } +h2 { color: white; background: #85774A; } +h3 { color: white; background: #9D936E; } +h4 { color: white; background: #9D936E; } + +a { color: #BA6D36; } + +</style> +</head> +<body> +<a NAME="top" ID="top"></a> +<h1>eric7.DocumentationTools.ModuleDocumentor</h1> + +<p> +Module implementing the builtin documentation generator. +</p> +<p> +The different parts of the module document are assembled from the parsed +Python file. The appearance is determined by several templates defined within +this module. +</p> +<h3>Global Attributes</h3> + +<table> +<tr><td>_event</td></tr><tr><td>_signal</td></tr> +</table> +<h3>Classes</h3> + +<table> + +<tr> +<td><a href="#ModuleDocument">ModuleDocument</a></td> +<td>Class implementing the builtin documentation generator.</td> +</tr> +<tr> +<td><a href="#TagError">TagError</a></td> +<td>Exception class raised, if an invalid documentation tag was found.</td> +</tr> +</table> +<h3>Functions</h3> + +<table> +<tr><td>None</td></tr> +</table> +<hr /> +<hr /> +<a NAME="ModuleDocument" ID="ModuleDocument"></a> +<h2>ModuleDocument</h2> + +<p> + Class implementing the builtin documentation generator. +</p> +<h3>Derived from</h3> +None +<h3>Class Attributes</h3> + +<table> +<tr><td>None</td></tr> +</table> +<h3>Class Methods</h3> + +<table> +<tr><td>None</td></tr> +</table> +<h3>Methods</h3> + +<table> + +<tr> +<td><a href="#ModuleDocument.__init__">ModuleDocument</a></td> +<td>Constructor</td> +</tr> +<tr> +<td><a href="#ModuleDocument.__checkDeprecated">__checkDeprecated</a></td> +<td>Private method to check, if the object to be documented contains a deprecated flag.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.__formatCrossReferenceEntry">__formatCrossReferenceEntry</a></td> +<td>Private method to format a cross reference entry.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.__formatDescription">__formatDescription</a></td> +<td>Private method to format the contents of the documentation string.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.__genClassListSection">__genClassListSection</a></td> +<td>Private method to generate the section listing all classes of the module.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.__genClassesSection">__genClassesSection</a></td> +<td>Private method to generate the document section with details about classes.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.__genDescriptionListSection">__genDescriptionListSection</a></td> +<td>Private method to generate the list section of a description.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.__genFunctionListSection">__genFunctionListSection</a></td> +<td>Private method to generate the section listing all functions of the module.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.__genFunctionsSection">__genFunctionsSection</a></td> +<td>Private method to generate the document section with details about functions.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.__genGlobalsListSection">__genGlobalsListSection</a></td> +<td>Private method to generate the section listing all global attributes of the module.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.__genListSection">__genListSection</a></td> +<td>Private method to generate a list section of the document.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.__genMethodSection">__genMethodSection</a></td> +<td>Private method to generate the method details section.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.__genMethodsListSection">__genMethodsListSection</a></td> +<td>Private method to generate the methods list section of a class.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.__genModuleSection">__genModuleSection</a></td> +<td>Private method to generate the body of the document.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.__genParagraphs">__genParagraphs</a></td> +<td>Private method to assemble the descriptive paragraphs of a docstring.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.__genParamDescriptionListSection">__genParamDescriptionListSection</a></td> +<td>Private method to generate the list section of a description.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.__genRbModulesClassesListSection">__genRbModulesClassesListSection</a></td> +<td>Private method to generate the classes list section of a Ruby module.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.__genRbModulesClassesSection">__genRbModulesClassesSection</a></td> +<td>Private method to generate the Ruby module classes details section.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.__genRbModulesListSection">__genRbModulesListSection</a></td> +<td>Private method to generate the section listing all modules of the file (Ruby only).</td> +</tr> +<tr> +<td><a href="#ModuleDocument.__genRbModulesSection">__genRbModulesSection</a></td> +<td>Private method to generate the document section with details about Ruby modules.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.__genSeeListSection">__genSeeListSection</a></td> +<td>Private method to generate the "see also" list section of a description.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.__getShortDescription">__getShortDescription</a></td> +<td>Private method to determine the short description of an object.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.__processInlineTags">__processInlineTags</a></td> +<td>Private method to process inline tags.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.description">description</a></td> +<td>Public method used to get the description of the module.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.genDocument">genDocument</a></td> +<td>Public method to generate the source code documentation.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.getQtHelpKeywords">getQtHelpKeywords</a></td> +<td>Public method to retrieve the parts for the QtHelp keywords section.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.isEmpty">isEmpty</a></td> +<td>Public method to determine, if the module contains any classes or functions.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.name">name</a></td> +<td>Public method used to get the module name.</td> +</tr> +<tr> +<td><a href="#ModuleDocument.shortDescription">shortDescription</a></td> +<td>Public method used to get the short description of the module.</td> +</tr> +</table> +<h3>Static Methods</h3> + +<table> +<tr><td>None</td></tr> +</table> + +<a NAME="ModuleDocument.__init__" ID="ModuleDocument.__init__"></a> +<h4>ModuleDocument (Constructor)</h4> +<b>ModuleDocument</b>(<i>module, colors, stylesheet=None</i>) + +<p> + Constructor +</p> +<dl> + +<dt><i>module</i></dt> +<dd> +the information of the parsed Python file +</dd> +<dt><i>colors</i></dt> +<dd> +dictionary specifying the various colors for the output + (dictionary of strings) +</dd> +<dt><i>stylesheet</i></dt> +<dd> +the style to be used for the generated pages (string) +</dd> +</dl> +<a NAME="ModuleDocument.__checkDeprecated" ID="ModuleDocument.__checkDeprecated"></a> +<h4>ModuleDocument.__checkDeprecated</h4> +<b>__checkDeprecated</b>(<i>descr</i>) + +<p> + Private method to check, if the object to be documented contains a + deprecated flag. +</p> +<dl> + +<dt><i>descr</i></dt> +<dd> +documentation string (string) +</dd> +</dl> +<dl> +<dt>Return:</dt> +<dd> +flag indicating the deprecation status (boolean) +</dd> +</dl> +<a NAME="ModuleDocument.__formatCrossReferenceEntry" ID="ModuleDocument.__formatCrossReferenceEntry"></a> +<h4>ModuleDocument.__formatCrossReferenceEntry</h4> +<b>__formatCrossReferenceEntry</b>(<i>entry</i>) + +<p> + Private method to format a cross reference entry. +</p> +<p> + This cross reference entry looks like "package.module#member label". +</p> +<dl> + +<dt><i>entry</i></dt> +<dd> +the entry to be formatted (string) +</dd> +</dl> +<dl> +<dt>Return:</dt> +<dd> +formatted entry (string) +</dd> +</dl> +<a NAME="ModuleDocument.__formatDescription" ID="ModuleDocument.__formatDescription"></a> +<h4>ModuleDocument.__formatDescription</h4> +<b>__formatDescription</b>(<i>descr</i>) + +<p> + Private method to format the contents of the documentation string. +</p> +<dl> + +<dt><i>descr</i></dt> +<dd> +The contents of the documentation string. (string) +</dd> +</dl> +<dl> +<dt>Return:</dt> +<dd> +The formatted contents of the documentation string. (string) +</dd> +</dl> +<dl> + +<dt>Raises <b>TagError</b>:</dt> +<dd> +A tag doesn't have the correct number + of arguments. +</dd> +</dl> +<a NAME="ModuleDocument.__genClassListSection" ID="ModuleDocument.__genClassListSection"></a> +<h4>ModuleDocument.__genClassListSection</h4> +<b>__genClassListSection</b>(<i></i>) + +<p> + Private method to generate the section listing all classes of the + module. +</p> +<dl> +<dt>Return:</dt> +<dd> +The classes list section. (string) +</dd> +</dl> +<a NAME="ModuleDocument.__genClassesSection" ID="ModuleDocument.__genClassesSection"></a> +<h4>ModuleDocument.__genClassesSection</h4> +<b>__genClassesSection</b>(<i></i>) + +<p> + Private method to generate the document section with details about + classes. +</p> +<dl> +<dt>Return:</dt> +<dd> +The classes details section. (string) +</dd> +</dl> +<a NAME="ModuleDocument.__genDescriptionListSection" ID="ModuleDocument.__genDescriptionListSection"></a> +<h4>ModuleDocument.__genDescriptionListSection</h4> +<b>__genDescriptionListSection</b>(<i>dictionary, template</i>) + +<p> + Private method to generate the list section of a description. +</p> +<dl> + +<dt><i>dictionary</i></dt> +<dd> +Dictionary containing the info for the + list section. +</dd> +<dt><i>template</i></dt> +<dd> +The template to be used for the list. (string) +</dd> +</dl> +<dl> +<dt>Return:</dt> +<dd> +The list section. (string) +</dd> +</dl> +<a NAME="ModuleDocument.__genFunctionListSection" ID="ModuleDocument.__genFunctionListSection"></a> +<h4>ModuleDocument.__genFunctionListSection</h4> +<b>__genFunctionListSection</b>(<i></i>) + +<p> + Private method to generate the section listing all functions of the + module. +</p> +<dl> +<dt>Return:</dt> +<dd> +The functions list section. (string) +</dd> +</dl> +<a NAME="ModuleDocument.__genFunctionsSection" ID="ModuleDocument.__genFunctionsSection"></a> +<h4>ModuleDocument.__genFunctionsSection</h4> +<b>__genFunctionsSection</b>(<i></i>) + +<p> + Private method to generate the document section with details about + functions. +</p> +<dl> +<dt>Return:</dt> +<dd> +The functions details section. (string) +</dd> +</dl> +<a NAME="ModuleDocument.__genGlobalsListSection" ID="ModuleDocument.__genGlobalsListSection"></a> +<h4>ModuleDocument.__genGlobalsListSection</h4> +<b>__genGlobalsListSection</b>(<i>class_=None</i>) + +<p> + Private method to generate the section listing all global attributes of + the module. +</p> +<dl> + +<dt><i>class_</i></dt> +<dd> +reference to a class object (Class) +</dd> +</dl> +<dl> +<dt>Return:</dt> +<dd> +The globals list section. (string) +</dd> +</dl> +<a NAME="ModuleDocument.__genListSection" ID="ModuleDocument.__genListSection"></a> +<h4>ModuleDocument.__genListSection</h4> +<b>__genListSection</b>(<i>names, sectionDict, kwSuffix=""</i>) + +<p> + Private method to generate a list section of the document. +</p> +<dl> + +<dt><i>names</i></dt> +<dd> +The names to appear in the list. (list of strings) +</dd> +<dt><i>sectionDict</i></dt> +<dd> +dictionary containing all relevant information + (dict) +</dd> +<dt><i>kwSuffix</i></dt> +<dd> +suffix to be used for the QtHelp keywords (string) +</dd> +</dl> +<dl> +<dt>Return:</dt> +<dd> +list section (string) +</dd> +</dl> +<a NAME="ModuleDocument.__genMethodSection" ID="ModuleDocument.__genMethodSection"></a> +<h4>ModuleDocument.__genMethodSection</h4> +<b>__genMethodSection</b>(<i>obj, className, modifierFilter</i>) + +<p> + Private method to generate the method details section. +</p> +<dl> + +<dt><i>obj</i></dt> +<dd> +reference to the object being formatted +</dd> +<dt><i>className</i></dt> +<dd> +name of the class containing the method (string) +</dd> +<dt><i>modifierFilter</i></dt> +<dd> +filter value designating the method types +</dd> +</dl> +<dl> +<dt>Return:</dt> +<dd> +method list and method details section (tuple of two string) +</dd> +</dl> +<a NAME="ModuleDocument.__genMethodsListSection" ID="ModuleDocument.__genMethodsListSection"></a> +<h4>ModuleDocument.__genMethodsListSection</h4> +<b>__genMethodsListSection</b>(<i>names, sectionDict, className, clsName, includeInit=True</i>) + +<p> + Private method to generate the methods list section of a class. +</p> +<dl> + +<dt><i>names</i></dt> +<dd> +names to appear in the list (list of strings) +</dd> +<dt><i>sectionDict</i></dt> +<dd> +dictionary containing all relevant information + (dict) +</dd> +<dt><i>className</i></dt> +<dd> +class name containing the names +</dd> +<dt><i>clsName</i></dt> +<dd> +visible class name containing the names +</dd> +<dt><i>includeInit</i></dt> +<dd> +flag indicating to include the __init__ method + (boolean) +</dd> +</dl> +<dl> +<dt>Return:</dt> +<dd> +methods list section (string) +</dd> +</dl> +<a NAME="ModuleDocument.__genModuleSection" ID="ModuleDocument.__genModuleSection"></a> +<h4>ModuleDocument.__genModuleSection</h4> +<b>__genModuleSection</b>(<i></i>) + +<p> + Private method to generate the body of the document. +</p> +<dl> +<dt>Return:</dt> +<dd> +The body of the document. (string) +</dd> +</dl> +<a NAME="ModuleDocument.__genParagraphs" ID="ModuleDocument.__genParagraphs"></a> +<h4>ModuleDocument.__genParagraphs</h4> +<b>__genParagraphs</b>(<i>lines</i>) + +<p> + Private method to assemble the descriptive paragraphs of a docstring. +</p> +<p> + A paragraph is made up of a number of consecutive lines without + an intermediate empty line. Empty lines are treated as a paragraph + delimiter. +</p> +<dl> + +<dt><i>lines</i></dt> +<dd> +A list of individual lines. (list of strings) +</dd> +</dl> +<dl> +<dt>Return:</dt> +<dd> +Ready formatted paragraphs. (string) +</dd> +</dl> +<a NAME="ModuleDocument.__genParamDescriptionListSection" ID="ModuleDocument.__genParamDescriptionListSection"></a> +<h4>ModuleDocument.__genParamDescriptionListSection</h4> +<b>__genParamDescriptionListSection</b>(<i>_list</i>) + +<p> + Private method to generate the list section of a description. +</p> +<dl> + +<dt><i>_list</i></dt> +<dd> +list containing the info for the parameter description + list section (list of lists with three elements) +</dd> +</dl> +<dl> +<dt>Return:</dt> +<dd> +formatted list section (string) +</dd> +</dl> +<a NAME="ModuleDocument.__genRbModulesClassesListSection" ID="ModuleDocument.__genRbModulesClassesListSection"></a> +<h4>ModuleDocument.__genRbModulesClassesListSection</h4> +<b>__genRbModulesClassesListSection</b>(<i>names, sectionDict, moduleName</i>) + +<p> + Private method to generate the classes list section of a Ruby module. +</p> +<dl> + +<dt><i>names</i></dt> +<dd> +The names to appear in the list. (list of strings) +</dd> +<dt><i>sectionDict</i></dt> +<dd> +dictionary containing all relevant information + (dict) +</dd> +<dt><i>moduleName</i></dt> +<dd> +name of the Ruby module containing the classes + (string) +</dd> +</dl> +<dl> +<dt>Return:</dt> +<dd> +The list section. (string) +</dd> +</dl> +<a NAME="ModuleDocument.__genRbModulesClassesSection" ID="ModuleDocument.__genRbModulesClassesSection"></a> +<h4>ModuleDocument.__genRbModulesClassesSection</h4> +<b>__genRbModulesClassesSection</b>(<i>obj, modName</i>) + +<p> + Private method to generate the Ruby module classes details section. +</p> +<dl> + +<dt><i>obj</i></dt> +<dd> +Reference to the object being formatted. +</dd> +<dt><i>modName</i></dt> +<dd> +Name of the Ruby module containing the classes. (string) +</dd> +</dl> +<dl> +<dt>Return:</dt> +<dd> +The classes list and classes details section. + (tuple of two string) +</dd> +</dl> +<a NAME="ModuleDocument.__genRbModulesListSection" ID="ModuleDocument.__genRbModulesListSection"></a> +<h4>ModuleDocument.__genRbModulesListSection</h4> +<b>__genRbModulesListSection</b>(<i></i>) + +<p> + Private method to generate the section listing all modules of the file + (Ruby only). +</p> +<dl> +<dt>Return:</dt> +<dd> +The modules list section. (string) +</dd> +</dl> +<a NAME="ModuleDocument.__genRbModulesSection" ID="ModuleDocument.__genRbModulesSection"></a> +<h4>ModuleDocument.__genRbModulesSection</h4> +<b>__genRbModulesSection</b>(<i></i>) + +<p> + Private method to generate the document section with details about + Ruby modules. +</p> +<dl> +<dt>Return:</dt> +<dd> +The Ruby modules details section. (string) +</dd> +</dl> +<a NAME="ModuleDocument.__genSeeListSection" ID="ModuleDocument.__genSeeListSection"></a> +<h4>ModuleDocument.__genSeeListSection</h4> +<b>__genSeeListSection</b>(<i>_list, template</i>) + +<p> + Private method to generate the "see also" list section of a + description. +</p> +<dl> + +<dt><i>_list</i></dt> +<dd> +List containing the info for the section. +</dd> +<dt><i>template</i></dt> +<dd> +The template to be used for the list. (string) +</dd> +</dl> +<dl> +<dt>Return:</dt> +<dd> +The list section. (string) +</dd> +</dl> +<a NAME="ModuleDocument.__getShortDescription" ID="ModuleDocument.__getShortDescription"></a> +<h4>ModuleDocument.__getShortDescription</h4> +<b>__getShortDescription</b>(<i>desc</i>) + +<p> + Private method to determine the short description of an object. +</p> +<p> + The short description is just the first non empty line of the + documentation string. +</p> +<dl> + +<dt><i>desc</i></dt> +<dd> +The documentation string. (string) +</dd> +</dl> +<dl> +<dt>Return:</dt> +<dd> +The short description. (string) +</dd> +</dl> +<a NAME="ModuleDocument.__processInlineTags" ID="ModuleDocument.__processInlineTags"></a> +<h4>ModuleDocument.__processInlineTags</h4> +<b>__processInlineTags</b>(<i>desc</i>) + +<p> + Private method to process inline tags. +</p> +<dl> + +<dt><i>desc</i></dt> +<dd> +One line of the description (string) +</dd> +</dl> +<dl> +<dt>Return:</dt> +<dd> +processed line with inline tags expanded (string) +</dd> +</dl> +<dl> + +<dt>Raises <b>TagError</b>:</dt> +<dd> +raised to indicate an invalid tag +</dd> +</dl> +<a NAME="ModuleDocument.description" ID="ModuleDocument.description"></a> +<h4>ModuleDocument.description</h4> +<b>description</b>(<i></i>) + +<p> + Public method used to get the description of the module. +</p> +<dl> +<dt>Return:</dt> +<dd> +The description of the module. (string) +</dd> +</dl> +<a NAME="ModuleDocument.genDocument" ID="ModuleDocument.genDocument"></a> +<h4>ModuleDocument.genDocument</h4> +<b>genDocument</b>(<i></i>) + +<p> + Public method to generate the source code documentation. +</p> +<dl> +<dt>Return:</dt> +<dd> +The source code documentation. (string) +</dd> +</dl> +<a NAME="ModuleDocument.getQtHelpKeywords" ID="ModuleDocument.getQtHelpKeywords"></a> +<h4>ModuleDocument.getQtHelpKeywords</h4> +<b>getQtHelpKeywords</b>(<i></i>) + +<p> + Public method to retrieve the parts for the QtHelp keywords section. +</p> +<dl> +<dt>Return:</dt> +<dd> +list of tuples containing the name (string) and the ref + (string). The ref is without the filename part. +</dd> +</dl> +<a NAME="ModuleDocument.isEmpty" ID="ModuleDocument.isEmpty"></a> +<h4>ModuleDocument.isEmpty</h4> +<b>isEmpty</b>(<i></i>) + +<p> + Public method to determine, if the module contains any classes or + functions. +</p> +<dl> +<dt>Return:</dt> +<dd> +Flag indicating an empty module (i.e. __init__.py without + any contents) +</dd> +</dl> +<a NAME="ModuleDocument.name" ID="ModuleDocument.name"></a> +<h4>ModuleDocument.name</h4> +<b>name</b>(<i></i>) + +<p> + Public method used to get the module name. +</p> +<dl> +<dt>Return:</dt> +<dd> +The name of the module. (string) +</dd> +</dl> +<a NAME="ModuleDocument.shortDescription" ID="ModuleDocument.shortDescription"></a> +<h4>ModuleDocument.shortDescription</h4> +<b>shortDescription</b>(<i></i>) + +<p> + Public method used to get the short description of the module. +</p> +<p> + The short description is just the first line of the modules + description. +</p> +<dl> +<dt>Return:</dt> +<dd> +The short description of the module. (string) +</dd> +</dl> +<div align="right"><a href="#top">Up</a></div> +<hr /> +<hr /> +<a NAME="TagError" ID="TagError"></a> +<h2>TagError</h2> + +<p> + Exception class raised, if an invalid documentation tag was found. +</p> +<h3>Derived from</h3> +Exception +<h3>Class Attributes</h3> + +<table> +<tr><td>None</td></tr> +</table> +<h3>Class Methods</h3> + +<table> +<tr><td>None</td></tr> +</table> +<h3>Methods</h3> + +<table> +<tr><td>None</td></tr> +</table> +<h3>Static Methods</h3> + +<table> +<tr><td>None</td></tr> +</table> + +<div align="right"><a href="#top">Up</a></div> +<hr /> +</body></html> \ No newline at end of file