Documentation/Source/eric5.DocumentationTools.ModuleDocumentor.html

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN'
'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
<html><head>
<title>eric5.DocumentationTools.ModuleDocumentor</title>
<style>
body {
    background: white;
    margin: 0em 1em 10em 1em;
    color: black;
}

h1 { color: white; background: #85774A; }
h2 { color: white; background: #85774A; }
h3 { color: black; background: #C1BBA4; }
h4 { color: black; background: #C1BBA4; }
    
a { color: #C07037; }

</style>
</head>
<body><a NAME="top" ID="top"></a>
<h1>eric5.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>
object
<h3>Class Attributes</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>
<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>desc</i></dt>
<dd>
The documentation string. (string)
</dd>
</dl><dl>
<dt>Returns:</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>Returns:</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>Returns:</dt>
<dd>
The formated 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>Returns:</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>Returns:</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>Returns:</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>Returns:</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>Returns:</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>Returns:</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, dict, 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>dict</i></dt>
<dd>
A dictionary containing all relevant information.
</dd><dt><i>kwSuffix</i></dt>
<dd>
suffix to be used for the QtHelp keywords (string)
</dd>
</dl><dl>
<dt>Returns:</dt>
<dd>
The list section. (string)
</dd>
</dl><a NAME="ModuleDocument.__genMethodSection" ID="ModuleDocument.__genMethodSection"></a>
<h4>ModuleDocument.__genMethodSection</h4>
<b>__genMethodSection</b>(<i>obj, className</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>
</dl><dl>
<dt>Returns:</dt>
<dd>
The 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, dict, className, clsName</i>)
<p>
        Private method to generate the methods list section of a class.
</p><dl>
<dt><i>names</i></dt>
<dd>
The names to appear in the list. (list of strings)
</dd><dt><i>dict</i></dt>
<dd>
A dictionary containing all relevant information.
</dd><dt><i>className</i></dt>
<dd>
The class name containing the names.
</dd><dt><i>clsName</i></dt>
<dd>
The visible class name containing the names.
</dd>
</dl><dl>
<dt>Returns:</dt>
<dd>
The 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>Returns:</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>Returns:</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, template</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
            list section.
</dd><dt><i>template</i></dt>
<dd>
The template to be used for the list. (string)
</dd>
</dl><dl>
<dt>Returns:</dt>
<dd>
The list section. (string)
</dd>
</dl><a NAME="ModuleDocument.__genRbModulesClassesListSection" ID="ModuleDocument.__genRbModulesClassesListSection"></a>
<h4>ModuleDocument.__genRbModulesClassesListSection</h4>
<b>__genRbModulesClassesListSection</b>(<i>names, dict, 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>dict</i></dt>
<dd>
A dictionary containing all relevant information.
</dd><dt><i>moduleName</i></dt>
<dd>
Name of the Ruby module containing the classes. (string)
</dd>
</dl><dl>
<dt>Returns:</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>Returns:</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>Returns:</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>Returns:</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>Returns:</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>Returns:</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>Returns:</dt>
<dd>
processed line with inline tags expanded (string)
</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>Returns:</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>Returns:</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>Returns:</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>Returns:</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>Returns:</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>Returns:</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>Methods</h3>
<table>
<tr><td>None</td></tr>
</table>

<div align="right"><a href="#top">Up</a></div>
<hr />
</body></html>