# # Structured docset and formatters for HappyDoc. # # This code is based on Doug Hellmann's docset from HappyDoc # project. # # Copyright (C) 2001 by wrobell . # # This software comes with ABSOLUTELY NO WARRANTY. # This is free software, and you are welcome to redistribute it # under certain conditions. For details see COPYING file. # """Documentation set which writes output to multiple structured files. This docset creates file for every module and defined class. Documentation structure is rendered with formatter's *process* methods (processClass, processModule, processImport, etc.). There is special method -- processRoot. It is invoked when new output is opened or closed. These all methods can be called in four different stages (element -- i.e. class or module): 1. PRE -- before any of elements processing 2. START -- before an element processing 3. END -- after an element processing 4. POST -- after all element processing Formatters can produce index of created by this docset files with packageIndex, moduleIndex and classIndex methods. """ __rcs_info__ = { # creation information 'module_name':'$RCSfile: docset_mstruct.py,v $', 'creator':'wrobell ', 'project':'shd', 'created':'24.08.2001', # current information 'author':'$Author: doughellmann $', 'version':'$Revision: 1.4 $', 'date':'$Date: 2002/08/04 12:05:20 $', 'locker':'$Locker: $', } import happydoclib.happydocset from happydoclib.docset.mstruct_const import * def entryPoint(): "Return info about this module to the HappyDoc dynamic loader." return { 'name': 'mstruct', 'factory': MStructDocSet, } # # Do not use multiple lines in the class docstring, since it shows up as # part of the generated help message for the app and multiple lines throws # off the formatting. # class MStructDocSet(happydoclib.happydocset.DocSet): """Documentation set written to multiple structured files. Parameters *Adds no additional parameters not understood by DocSet.* """ def __init__(self, **args): happydoclib.happydocset.DocSet.__init__(self, **args) def openOutput(self, name, title, subtitle, rtype=INDEX_FILE): """Opens output, where documentation will be written. Arguments 'name' -- output file name 'title' -- title of documentation file 'subtitle' -- subtitle of documentation file 'rtype' -- gives info whether index, module or class file will be opened Returns file object of opened documentation file. """ output=happydoclib.happydocset.DocSet.openOutput(self, name, title, subtitle) self._formatter.processRoot(output, START, rtype) return output def closeOutput(self, output, rtype=INDEX_FILE): """Closes output, where documentation has been written. Arguments 'output' -- file object of opened documentation file 'rtype' -- gives info whether index, module or class file will be closed """ self._formatter.processRoot(output, END, rtype) happydoclib.happydocset.DocSet.closeOutput(self, output) def write(self): "Write the documentation set to the output." self.statusMessage('Beginning to write...') # get the name of and open the docset index file self._index_file_name=self.getFullOutputNameForObject(None) self._index_file=self.openOutput(self._index_file_name, self._title, '', INDEX_FILE) # write the output self._writeModules() self._writePackages() # close things up self.closeOutput(self._index_file, INDEX_FILE) self.close() return def _writePackages(self): "Output documentation for all packages." self.statusMessage() self.statusMessage('Writing package documentation...') package_items=self._all_packages.items() package_items.sort() formatter=self._formatter output=self._index_file formatter.processPackage(None, output, PRE) for package_name, package in package_items: formatter.processPackage(package, output, START) formatter.packageIndex(package, output) package.write() formatter.processPackage(package, output, END) formatter.processPackage(None, output, POST) def _writeModules(self): "Output documentation for all modules." self.statusMessage() self.statusMessage('Writing module documentation...') module_names=self._all_modules.keys() module_names.sort() self._formatter.processModule(None, self._index_file, PRE) for module_name in module_names: self._writeModule(module_name) self._formatter.processModule(None, self._index_file, POST) def _writeModule(self, module_name): """Output the documentation for the named module. Arguments 'module_name' -- name of the module """ formatter=self._formatter module=self._all_modules[module_name] formatter.moduleIndex(module, self._index_file) output_name=self.getFullOutputNameForObject(module) output=self.openOutput(output_name, 'Module: %s' % module_name, module.getFilename(), MODULE_FILE) # start the module tag formatter.processModule(module, output, START) imported_modules=module.getImportData() if imported_modules: formatter.processImport(None, module, output, PRE) for name, symbols in imported_modules: formatter.processImport(name, module, output, START) if symbols: formatter.processImportSymbol(symbols, output, START) formatter.processImportSymbol(symbols, output, END) formatter.processImport(name, module, output, END) formatter.processImport(None, module, output, POST) # write the doc string formatter.processDocString(module, output, START) formatter.writeText(module.getDocString(), output) formatter.processDocString(module, output, END) # write the info for the classes in this module class_names=self._filterNames(module.getClassNames()) if class_names: class_names.sort() formatter.processClass(None, output, PRE) for class_name in class_names: c=module.getClassInfo(class_name) formatter.classIndex(c, output) class_output_name=self.getFullOutputNameForObject(c) class_output=self.openOutput(class_output_name, 'Class: %s' % class_name, \ module.getFilename(), CLASS_FILE) self._writeClass(module, class_name, class_output) self.closeOutput(class_output, CLASS_FILE) formatter.processClass(None, output, POST) formatter.comment('END: Classes of module %s' % module_name, output) # finish module section formatter.processModule(module, output, END) self.closeOutput(output, MODULE_FILE) def _writeBaseClassNames(self, parent, cinfo, output, indent=0): """Output the base class hierarchy for the given class. Arguments 'parent' -- info about class parent (module, class) 'cinfo' -- class info 'output' -- current output file object """ base_classes=cinfo.getBaseClassNames() formatter=self._formatter if base_classes: formatter.processClassBase(cinfo, None, output, PRE) for name in base_classes: formatter.processClassBase(cinfo, name, output, START) formatter.processClassBase(cinfo, name, output, END) formatter.processClassBase(cinfo, None, output, POST) def _writeClass(self, parent, class_name, output): """Output the documentation for the class in the parent object. Arguments 'parent' -- info about class parent (module, class) 'class_name' -- name of the class 'output' -- current output file object """ class_info=parent.getClassInfo(class_name) formatter=self._formatter formatter.processClass(class_info, output, START) formatter.processDocString(class_info, output, START) formatter.writeText(class_info.getDocString(), output) formatter.processDocString(class_info, output, END) # base class hierarchy base_classes=class_info.getBaseClassNames() if base_classes: self._writeBaseClassNames(parent, class_info, output) # write the info for the methods of this class method_names=self._filterNames(class_info.getMethodNames()) if method_names: method_names.sort() for method_name in method_names: self._writeFunction(method_name, class_info.getMethodInfo, output) formatter.processClass(class_info, output, END) def _writeFunction(self, function_name, getInfo, output): """Output the documentation for the function in the parent object. Arguments 'function_name' -- the function name 'getInfo' -- reference to method, which will return function info 'output' -- current output file object """ function=getInfo(function_name) formatter=self._formatter formatter.processFunction(function, output, START) # function signature self._formatter.processParam(None, output, PRE) for param in function.getParameterNames(): info=(param, function)+function.getParameterInfo(param) self._formatter.processParam(info, output, START) self._formatter.processParam(info, output, END) self._formatter.processParam(None, output, POST) # exceptions exception_names=function.getExceptionNames() if len(exception_names)>0: exception_names.sort() formatter=self._formatter formatter.processException(None, output, PRE) for name in exception_names: #name=re.compile('([A-Za-z]+),').search(name).group(1) einfo=function.getExceptionInfo(name) # if there is no exception info, then name of # the exception becomes the info if not einfo: einfo=name formatter.processException(einfo, output, START) formatter.processException(einfo, output, END) formatter.processException(None, output, POST) # output docstring formatter.processDocString(function, output, START) self._formatter.writeText(function.getDocString(), output) formatter.processDocString(function, output, END) formatter.processFunction(function, output, END)