eric7.DocumentationTools.ModuleDocumentor

Module implementing the builtin documentation generator.

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.

Global Attributes

_event
_signal

Classes

ModuleDocument Class implementing the builtin documentation generator.
TagError Exception class raised, if an invalid documentation tag was found.

Functions

None


ModuleDocument

Class implementing the builtin documentation generator.

Derived from

None

Class Attributes

None

Class Methods

None

Methods

ModuleDocument Constructor
__checkDeprecated Private method to check, if the object to be documented contains a deprecated flag.
__formatCrossReferenceEntry Private method to format a cross reference entry.
__formatDescription Private method to format the contents of the documentation string.
__genClassListSection Private method to generate the section listing all classes of the module.
__genClassesSection Private method to generate the document section with details about classes.
__genDescriptionListSection Private method to generate the list section of a description.
__genFunctionListSection Private method to generate the section listing all functions of the module.
__genFunctionsSection Private method to generate the document section with details about functions.
__genGlobalsListSection Private method to generate the section listing all global attributes of the module.
__genListSection Private method to generate a list section of the document.
__genMethodSection Private method to generate the method details section.
__genMethodsListSection Private method to generate the methods list section of a class.
__genModuleSection Private method to generate the body of the document.
__genParagraphs Private method to assemble the descriptive paragraphs of a docstring.
__genParamDescriptionListSection Private method to generate the list section of a description.
__genRbModulesClassesListSection Private method to generate the classes list section of a Ruby module.
__genRbModulesClassesSection Private method to generate the Ruby module classes details section.
__genRbModulesListSection Private method to generate the section listing all modules of the file (Ruby only).
__genRbModulesSection Private method to generate the document section with details about Ruby modules.
__genSeeListSection Private method to generate the "see also" list section of a description.
__getShortDescription Private method to determine the short description of an object.
__processInlineTags Private method to process inline tags.
description Public method used to get the description of the module.
genDocument Public method to generate the source code documentation.
getQtHelpKeywords Public method to retrieve the parts for the QtHelp keywords section.
isEmpty Public method to determine, if the module contains any classes or functions.
name Public method used to get the module name.
shortDescription Public method used to get the short description of the module.

Static Methods

None

ModuleDocument (Constructor)

ModuleDocument(module)

Constructor

module (str)
information of the parsed Python file

ModuleDocument.__checkDeprecated

__checkDeprecated(descr)

Private method to check, if the object to be documented contains a deprecated flag.

descr (str)
documentation string
Return:
flag indicating the deprecation status
Return Type:
bool

ModuleDocument.__formatCrossReferenceEntry

__formatCrossReferenceEntry(entry)

Private method to format a cross reference entry.

This cross reference entry looks like "package.module#member label".

entry (str)
entry to be formatted
Return:
formatted entry
Return Type:
str

ModuleDocument.__formatDescription

__formatDescription(descr)

Private method to format the contents of the documentation string.

descr (str)
contents of the documentation string
Return:
formatted contents of the documentation string
Return Type:
str
Raises TagError:
A tag doesn't have the correct number of arguments.

ModuleDocument.__genClassListSection

__genClassListSection()

Private method to generate the section listing all classes of the module.

Return:
classes list section
Return Type:
str

ModuleDocument.__genClassesSection

__genClassesSection()

Private method to generate the document section with details about classes.

Return:
classes details section
Return Type:
str

ModuleDocument.__genDescriptionListSection

__genDescriptionListSection(dictionary, template)

Private method to generate the list section of a description.

dictionary (dict)
dictionary containing the info for the list section
template (str)
template to be used for the list
Return:
list section
Return Type:
str

ModuleDocument.__genFunctionListSection

__genFunctionListSection()

Private method to generate the section listing all functions of the module.

Return:
functions list section
Return Type:
str

ModuleDocument.__genFunctionsSection

__genFunctionsSection()

Private method to generate the document section with details about functions.

Return:
functions details section
Return Type:
str

ModuleDocument.__genGlobalsListSection

__genGlobalsListSection(class_=None)

Private method to generate the section listing all global attributes of the module.

class_ (class)
reference to a class object
Return:
globals list section
Return Type:
str

ModuleDocument.__genListSection

__genListSection(names, sectionDict, kwSuffix="")

Private method to generate a list section of the document.

names (list of str)
names to appear in the list
sectionDict (dict)
dictionary containing all relevant information
kwSuffix (str)
suffix to be used for the QtHelp keywords
Return:
list section
Return Type:
str

ModuleDocument.__genMethodSection

__genMethodSection(obj, className, modifierFilter)

Private method to generate the method details section.

obj (class)
reference to the object being formatted
className (str)
name of the class containing the method
modifierFilter (str)
filter value designating the method types
Return:
method list and method details section
Return Type:
tuple of (str, str)

ModuleDocument.__genMethodsListSection

__genMethodsListSection(names, sectionDict, className, clsName, includeInit=True)

Private method to generate the methods list section of a class.

names (list of str)
names to appear in the list
sectionDict (dict)
dictionary containing all relevant information
className (str)
class name containing the names
clsName (str)
visible class name containing the names
includeInit (bool)
flag indicating to include the __init__ method
Return:
methods list section
Return Type:
str

ModuleDocument.__genModuleSection

__genModuleSection()

Private method to generate the body of the document.

Return:
body of the document
Return Type:
str

ModuleDocument.__genParagraphs

__genParagraphs(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.

lines (list of str)
list of individual lines
Return:
formatted paragraphs
Return Type:
str

ModuleDocument.__genParamDescriptionListSection

__genParamDescriptionListSection(_list)

Private method to generate the list section of a description.

_list (list of lists with three elements)
list containing the info for the parameter description list section
Return:
formatted list section
Return Type:
str

ModuleDocument.__genRbModulesClassesListSection

__genRbModulesClassesListSection(names, sectionDict, moduleName)

Private method to generate the classes list section of a Ruby module.

names (list of str)
names to appear in the list
sectionDict (dict)
dictionary containing all relevant information
moduleName (str)
name of the Ruby module containing the classes
Return:
list section
Return Type:
str

ModuleDocument.__genRbModulesClassesSection

__genRbModulesClassesSection(obj, modName)

Private method to generate the Ruby module classes details section.

obj (class)
reference to the object being formatted
modName (str)
name of the Ruby module containing the classes
Return:
classes list and classes details section
Return Type:
tuple of (str, str)

ModuleDocument.__genRbModulesListSection

__genRbModulesListSection()

Private method to generate the section listing all modules of the file (Ruby only).

Return:
modules list section
Return Type:
str

ModuleDocument.__genRbModulesSection

__genRbModulesSection()

Private method to generate the document section with details about Ruby modules.

Return:
Ruby modules details section
Return Type:
str

ModuleDocument.__genSeeListSection

__genSeeListSection(_list, template)

Private method to generate the "see also" list section of a description.

_list (list)
list containing the info for the section
template (str)
template to be used for the list
Return:
list section
Return Type:
str

ModuleDocument.__getShortDescription

__getShortDescription(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.

desc (str)
documentation string
Return:
short description
Return Type:
str

ModuleDocument.__processInlineTags

__processInlineTags(desc)

Private method to process inline tags.

desc (str)
one line of the description
Return:
processed line with inline tags expanded
Return Type:
str
Raises TagError:
raised to indicate an invalid tag

ModuleDocument.description

description()

Public method used to get the description of the module.

Return:
description of the module
Return Type:
str

ModuleDocument.genDocument

genDocument()

Public method to generate the source code documentation.

Return:
source code documentation
Return Type:
str

ModuleDocument.getQtHelpKeywords

getQtHelpKeywords()

Public method to retrieve the parts for the QtHelp keywords section.

Return:
list of tuples containing the name and the ref. The ref is without the filename part.
Return Type:
list of tuples of (str, str)

ModuleDocument.isEmpty

isEmpty()

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 Type:
bool

ModuleDocument.name

name()

Public method used to get the module name.

Return:
name of the module
Return Type:
str

ModuleDocument.shortDescription

shortDescription()

Public method used to get the short description of the module.

The short description is just the first line of the modules description.

Return:
short description of the module
Return Type:
str
Up


TagError

Exception class raised, if an invalid documentation tag was found.

Derived from

Exception

Class Attributes

None

Class Methods

None

Methods

None

Static Methods

None
Up