#!/usr/bin/env python # # $Id: docset_MultipleFile.py,v 1.7 2002/08/24 19:50:06 doughellmann Exp $ # # COPYRIGHT # # Permission to use, copy, modify, and distribute this software and # its documentation for any purpose and without fee is hereby # granted, provided that the above copyright notice appear in all # copies and that both that copyright notice and this permission # notice appear in supporting documentation, and that the name of # Doug Hellmann not be used in advertising or publicity pertaining # to distribution of the software without specific, written prior # permission. # # DISCLAIMER # # DOUG HELLMANN DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS # SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND # FITNESS, IN NO EVENT SHALL DOUG HELLMANN BE LIABLE FOR ANY # SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES # WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN # AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, # ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF # THIS SOFTWARE. # """Documentation set which writes output to multiple files. """ __rcs_info__ = { # # Creation Information # 'module_name':'$RCSfile: docset_MultipleFile.py,v $', 'creator':'Doug Hellmann ', 'project':'HappyDoc', 'created':'Sun, 26-Mar-2000 11:19:54 EST', # # Current Information # 'author':'$Author: doughellmann $', 'version':'$Revision: 1.7 $', 'date':'$Date: 2002/08/24 19:50:06 $', 'locker':'$Locker: $', } try: __version__ = __rcs_info__['version'].split(' ')[1] except: __version__ = '0.0' # # Import system modules # import glob import os import parser import re import string try: from cStringIO import StringIO except: from StringIO import StringIO import symbol import sys import token # # Import Local modules # import happydoclib # # Module # def entryPoint(): "Return info about this module to the dynamic loader." return { 'name':'MultiFile', 'factory':MultiFileDocSet, } # # 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 MultiFileDocSet(happydoclib.happydocset.DocSet): """Documentation set written to multiple files. Parameters *Adds no additional parameters not understood by DocSet.* """ def write(self): "Write the documentation set to the output." happydoclib.TRACE.into('MultiFileDocSet', 'write') self.statusMessage('Beginning to write %s...' % self.getName()) # # Get the name of and open the docset root file # self._root_name = self.getFullOutputNameForObject(None) happydoclib.TRACE.writeVar(root_name=self._root_name) self._root_node = self.openOutput( self._root_name, self._title, '' ) happydoclib.TRACE.writeVar(root_node=self._root_node) # # Get the description for the docset from the # file specified. # self._writeDescription( self._root_node ) # # Write the output # self._writePackages() self._writeModules() self._writePrewrittenFiles() self._writeTOC() self._writeIndex() # # Close things up # self.close() happydoclib.TRACE.outof() return def _writeDescription(self, output): """Write the contents of the description file in 'directoryName' to 'output'. """ name = self.getName() happydoclib.TRACE.into('MultiFileDocSet', '_writeDescription', name=name) happydoclib.TRACE.writeVar(description_filename=self._description_filename) description, input_type = self.getDescriptionAndFormat() # # If we have found a description, write it out. # if description: self._formatter.writeText( description, output, input_type, 0 ) happydoclib.TRACE.outof() return def _organizeSubNodesByDir(self, outputDict, inputDict, removePrefix=0): happydoclib.TRACE.into('MultiFileDocSet', '_organizeSubNodesByDir', outputDict=outputDict, inputDict=inputDict, removePrefix=removePrefix) items = inputDict.items() subnode_ids = [] # # Translate nodes to records showing what directory they are # in and what their names are. # for x in items: happydoclib.TRACE.into('inputDict.items()', 'loop', x=x) node_name = x[0] happydoclib.TRACE.writeVar(node_name=node_name) dir_name = happydoclib.path.dirname(x[1].getFilename()) happydoclib.TRACE.writeVar(dir_name=dir_name) if removePrefix: happydoclib.TRACE.write('removing prefix') dir_name = happydoclib.path.removeRelativePrefix( dir_name ) happydoclib.TRACE.writeVar(dir_name=dir_name) file_name = x[1].getFilename() happydoclib.TRACE.writeVar(file_name=file_name) rec = (dir_name, file_name, node_name) subnode_ids.append(rec) happydoclib.TRACE.outof(rec) # # For each subnode, record the node information in the list associated # with the directory where the node is located. # for dir_name, file_name, subnode_name in subnode_ids: happydoclib.TRACE.into('subnode_ids', 'loop', dir_name=dir_name, file_name=file_name, subnode_name=subnode_name) l = outputDict.get(dir_name, []) l.append( (file_name, subnode_name, inputDict) ) outputDict[dir_name] = l happydoclib.TRACE.outof() happydoclib.TRACE.outof() return def _writeTOC(self): "Output the TOC." happydoclib.TRACE.into('MultiFileDocSet', '_writeTOC') happydoclib.TRACE.writeVar(docset_name=self.getName()) self.statusMessage() self.statusMessage('Writing table of contents...') formatter = self._formatter # # Open a new section and list # formatter.comment('BEGIN: TOC', self._root_node) # # Build directory contents information for modules # and packages # subnodes_by_dir = {} self._organizeSubNodesByDir(subnodes_by_dir, self._all_modules, removePrefix=1) self._organizeSubNodesByDir(subnodes_by_dir, self._all_packages, removePrefix=0) happydoclib.TRACE.writeVar(subnodes_by_dir=subnodes_by_dir) # # Write Module references to TOC # dirs = subnodes_by_dir.keys() dirs.sort() if dirs: formatter.comment('BEGIN: TOC->Modules', self._root_node) formatter.pushSectionLevel(self._root_node) formatter.sectionHeader(self._root_node, 'Modules and Packages') for dir_name in dirs: happydoclib.TRACE.into('dirs', 'loop', directory=dir_name) relative_dir_name = happydoclib.path.removeRelativePrefix(dir_name) # # Open the section for this directory # subnode_set = subnodes_by_dir[dir_name] extra_files = self._directories_with_extra_docs.get(relative_dir_name, []) if dir_name and (dir_name[-1] != '/'): dir_name = dir_name + '/' formatter.descriptiveListHeader( self._root_node, dir_name) # # Write the list of extra files # which are in the directory being processed # if extra_files: formatter.comment('BEGIN: Extra files', self._root_node) for extra, summary, format in extra_files: # # Get the full name, including any fixup required # by the formatter. # full_extra_name = happydoclib.path.join(dir_name, extra) full_extra_name = formatter.fixUpOutputFilename(full_extra_name) # # Add reference to the TOC list # ref = formatter.getReference( full_extra_name, self._root_name, extra ) self.statusMessage('\tAdding reference to %s to TOC' % extra, 2) self.statusMessage('\tref="%s"' % ref, 3) formatter.descriptiveListItem( self._root_node, ref, summary, format, ) if extra_files: formatter.comment('END: Extra files', self._root_node) # # Write the list of modules # which are in the directory being processed # subnode_set.sort(lambda x, y: cmp(x[1], y[1])) for file_name, subnode_name, subnode_dict in subnode_set: happydoclib.TRACE.into('subnode_set', 'loop', file_name=file_name, subnode_name=subnode_name, subnode_dict=subnode_dict, ) subnode = subnode_dict[subnode_name] self.statusMessage('\tAdding %s to TOC' % subnode_name, 2) # # Build a reference to the documentation for the subnode # based on the type of referencing supported. # new_ref = subnode.getReference(formatter, self._root_node) happydoclib.TRACE.writeVar(root_node_name=self._root_node.name) happydoclib.TRACE.writeVar(new_ref=new_ref) if hasattr( subnode, 'getFullOutputNameForObject' ): happydoclib.TRACE.write('using getFullOutputNameForObject') ref = formatter.getReference( subnode.getFullOutputNameForObject(), self._root_name, subnode_name ) else: happydoclib.TRACE.write('using formatter getReference') ref = formatter.getReference(subnode, self._root_name, ) happydoclib.TRACE.writeVar(ref=ref) subnode_summary, subnode_format = subnode.getSummaryAndFormat() formatter.descriptiveListItem( self._root_node, ref, subnode_summary, subnode_format, ) happydoclib.TRACE.outof() formatter.descriptiveListFooter(self._root_node) happydoclib.TRACE.outof() # # Close the Modules section # if dirs: formatter.sectionFooter(self._root_node) formatter.popSectionLevel(self._root_node) formatter.comment('END: TOC->Modules', self._root_node) # # Close TOC section # formatter.comment('END: TOC', self._root_node) return def _writeIndex(self): "Output the index." self.statusMessage() self.statusMessage('IMPLEMENT Writing index...') return def _writePrewrittenFiles(self): """Convert the format of the discovered pre-written files. Convert the format of the discovered pre-written files. and write out new files as part of the docset. """ happydoclib.TRACE.into('MultiFileDocset', '_writePrewrittenFiles') directories_with_extra_docs = {} formatter = self._formatter for filename in self._prewritten_files: external_file = self.getExternalDocumentationFile(filename) summary = external_file.oneLiner() body = str(external_file) if not body: continue # # Convert the file using the formatter. # output_filename = formatter.getFullOutputNameForFile(filename) short_output_filename = output_filename[len(self.getOutputBaseDirectory())+1:] self.statusMessage('\tRewriting %s\n\t to %s' \ % (filename, short_output_filename), 2) external_file = self.getExternalDocumentationFile(filename) if external_file: summary = external_file.oneLiner() body = str(external_file) format = external_file.getInputType() else: summary = '' body = '' format = 'RawText' self.statusMessage('\t as %s' % format, 2) output = self.openOutput( output_filename, self._title, '' ) formatter.writeText( body, output, format ) self.closeOutput( output ) # # Generate a reference to the file in the TOC # relative_output_name = formatter.getOutputNameForFile( filename ) dir, base = happydoclib.path.split(relative_output_name) file_list = directories_with_extra_docs.get( dir, [] ) file_list.append( (base, summary, format) ) directories_with_extra_docs[dir] = file_list self._directories_with_extra_docs = directories_with_extra_docs happydoclib.TRACE.outof() 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() for package_name, package in package_items: package.write() return def _writeModules(self): "Output documentation for all modules." self.statusMessage() self.statusMessage('Writing module documentation...') module_names = self._all_modules.keys() module_names.sort() for module_name in module_names: self._writeModule( module_name ) return def _describeClassInModuleNode(self, output, class_output_file_name, class_info): happydoclib.TRACE.into('', '_describeClassInModuleNode', output=output, class_output_file_name=class_output_file_name, class_info=class_info, ) #ref = self._formatter.getReference(class_info, class_output_file_name) ref = self._formatter.getReference(class_info, output.name) class_info_summary, class_info_format = class_info.getSummaryAndFormat() self._formatter.descriptiveListItem( output, ref, class_info_summary, class_info_format, ) happydoclib.TRACE.outof() return def _writeModuleImportList(self, module_name, module, output_name, output): formatter = self._formatter # # Get some pre-formatted text we're going to reuse a lot # from_keyword = formatter.formatKeyword('from') import_keyword = formatter.formatKeyword('import') # # List the dependant modules # formatter.comment('Testing for imports %s' % module_name, output) imported_modules = module.getImportData() if imported_modules: formatter.comment('BEGIN: imports %s' % module_name, output) formatter.sectionHeader(output, 'Imported modules') formatter.listHeader(output, None, allowMultiColumn=0) for name, symbols in imported_modules: #print '\n\nDOCSET_MULTIPLEFILE: looking for %s' % name i_module = self.getSymbolInfo(name) if i_module: #print 'DOCSET_MULTIPLEFILE: got %s' % i_module #print 'DOCSET_MULTIPLEFILE: i_module is a %s' % \ # i_module.__class__.__name__ ref = i_module.getReference(formatter, output) #print 'DOCSET_MULTIPLEFILE: MODULE REFERENCE: ' #print 'DOCSET_MULTIPLEFILE: FROM:', output.name #print 'DOCSET_MULTIPLEFILE: TO:', ref else: ref = formatter.getPythonReference( name ) i_module = None if symbols: if i_module: # # Process the list of imported names and # generate references to the ones which are # recognized by our parser. # import_list = [] for i_name in symbols: i_info = i_module.getSymbolInfo(i_name) if i_info: i_ref = i_info.getReference(formatter, output) else: #print 'DOCSET_MULTIPLEFILE: UNABLE TO FIND %s in %s' % \ # (i_name, name) i_ref = i_name import_list.append(i_ref) else: import_list = symbols # # from X import Y, Z # formatter.listItem( output, '%s %s %s %s' % \ ( from_keyword, ref, import_keyword, string.join(import_list, ', ') ) ) else: # # import X # formatter.listItem( output, '%s %s' % (import_keyword, ref) ) formatter.listFooter(output) formatter.sectionFooter(output) formatter.comment('END: imports %s' % module_name, output) else: # # No imports # formatter.comment('No imports %s' % module_name, output) return def _writeModule(self, module_name): "Output the documentation for the module named." module = self._all_modules[module_name] output_name = self.getFullOutputNameForObject(module) output = self.openOutput(output_name, 'Module: %s' % module_name, module.getFilename()) formatter = self._formatter formatter.comment('BEGIN: Module %s' % module_name, output) # # Write the doc string # formatter.writeText( module.getDocString(), output, module.getDocStringFormat() ) # # Start the indented section # formatter.pushSectionLevel(output) # # Write list of imported symbols # self._writeModuleImportList(module_name, module, output_name, output) # # Write the info for the functions in this module # function_names = self._filterNames(module.getFunctionNames()) if function_names: formatter.comment('BEGIN: Functions of module %s' % module_name, output) formatter.sectionHeader( output, 'Functions' ) function_names.sort() # # TOC list # formatter.listHeader( output ) for function_name in function_names: formatter.listItem( output, formatter.getInternalReference( module.getFunctionInfo(function_name) ) ) formatter.listFooter( output ) # # Function descriptions # for function_name in function_names: self._writeFunction(function_name, module.getFunctionInfo, output) formatter.sectionFooter(output) formatter.comment('END: Functions of module %s' % module_name, output) # # Write the info for the classes in this module # class_names = self._filterNames(module.getClassNames()) if class_names: formatter.comment('BEGIN: Classes of module %s' % module_name, output) formatter.sectionHeader( output, 'Classes' ) formatter.descriptiveListHeader( output, None ) class_names.sort() for class_name in class_names: happydoclib.TRACE.into('class_names', 'loop', class_name=class_name) c = module.getClassInfo(class_name) class_output_name = self.getFullOutputNameForObject(c) happydoclib.TRACE.writeVar(class_output_name=class_output_name) self._describeClassInModuleNode(output, class_output_name , c) class_output = self.openOutput(class_output_name, 'Class: %s' % class_name, module.getFilename()) self._writeClass( module, class_name, class_output ) self.closeOutput(class_output) happydoclib.TRACE.outof() formatter.descriptiveListFooter(output) formatter.sectionFooter( output ) formatter.comment('END: Classes of module %s' % module_name, output) # # Finish that indented level. # formatter.sectionFooter(output) formatter.popSectionLevel(output) formatter.comment('END: Module %s' % module_name, output) # # Close the output file # self.closeOutput(output) return def _writeBaseclassNames(self, parent, classInfo, output, indent=0): "Output the base class hierarchy for the given class." base_classes = classInfo.getBaseClassNames() formatter = self._formatter if base_classes: if indent: formatter.indent(output) formatter.listHeader(output, None, allowMultiColumn=0) for name in base_classes: try: child = parent.getClassInfo(name) except KeyError: formatter.listItem( output, name ) else: formatter.listItem( output, formatter.getReference(child, output.name, ) ) if name != classInfo.getName(): self._writeBaseclassNames(parent, child, output, 1) formatter.listFooter(output) if indent: formatter.dedent(output) return def _writeClass(self, parent, class_name, output): "Output the documentation for the class in the parent object." happydoclib.TRACE.into('MultiFileDocSet', '_writeClass', parent=parent, class_name=class_name, output=output, ) class_info = parent.getClassInfo(class_name) formatter = self._formatter formatter.comment('BEGIN: Class %s' % class_name, output) formatter.writeText( class_info.getDocString(), output, class_info.getDocStringFormat(), ) # # Base class hierarchy # base_classes = self._filterNames(class_info.getBaseClassNames()) happydoclib.TRACE.writeVar(base_classes=base_classes) if base_classes: formatter.pushSectionLevel(output) formatter.sectionHeader(output, 'Base Classes') self._writeBaseclassNames(parent, class_info, output) formatter.sectionFooter(output) formatter.popSectionLevel(output) # # Start the indented section # formatter.pushSectionLevel(output) # # Write the info for the methods of this class # method_names = self._filterNames(class_info.getMethodNames()) if method_names: formatter.sectionHeader( output, 'Methods' ) method_names.sort() # # TOC list # formatter.listHeader( output ) for method_name in method_names: formatter.listItem( output, formatter.getInternalReference( class_info.getMethodInfo(method_name) ) ) formatter.listFooter( output ) for method_name in method_names: self._writeFunction(method_name, class_info.getMethodInfo, output) formatter.sectionFooter(output) # # Finish that indented level. # formatter.sectionFooter(output) formatter.popSectionLevel(output) formatter.comment('END: Class %s' % class_name, output) happydoclib.TRACE.outof() return def _writeFunctionParameter(self, name, info, output): '''Write a function parameter to the output. No indenting or formatting is performed. The output looks like:: name or name=default Parameters: name -- name of the parameter info -- tuple of (default_specified, default_value, default_value_type) concerning the default value of the parameter output -- destination for written output ''' formatter = self._formatter formatter.writeRaw(name, output) default_specified, default_value, default_value_type = info if default_specified: formatter.writeRaw('=', output) if default_value_type == token.STRING: formatter.writeRaw(`default_value`, output) elif default_value_type == token.NUMBER: formatter.writeRaw(str(default_value), output) else: #print 'FUNCTION DEFAULT VALUE (%s, %s): "%s"' % ( # type(default_value), # default_value_type or 'Unknown', # default_value) formatter.writeRaw(str(default_value), output) return def _writeFunctionSignature(self, function, output): """Write the function signature for 'function' to 'output'. Parameters function -- Instance of FunctionInfo from parseinfo module. output -- Where to write. """ formatter = self._formatter function_name = function.getName() signature_buffer = StringIO() signature_buffer.write('%s (' % function_name) parameter_names = function.getParameterNames() if parameter_names: if len(parameter_names) <= 2: for param in parameter_names: param_info = function.getParameterInfo(param) signature_buffer.write(' ') self._writeFunctionParameter(param, param_info, signature_buffer) if param != parameter_names[-1]: signature_buffer.write(',') signature_buffer.write(' ') else: signature_buffer.write('\n') indent = 8 #len(name) + 3 for param in parameter_names: signature_buffer.write(' ' * indent) param_info = function.getParameterInfo(param) self._writeFunctionParameter(param, param_info, signature_buffer) signature_buffer.write(',\n') signature_buffer.write('%s' % (' ' * indent)) signature_buffer.write(')\n') formatter.writeCode(signature_buffer.getvalue(), 'PlainText', output) return def _writeExceptionListForFunction(self, output, function, listHeader): """Write the list of exceptions raised by a function. Parameters output -- Where to write. function -- FunctionInfo from parseinfo module. listHeader -- Header for list being generated. """ formatter = self._formatter formatter.pushSectionLevel(output) formatter.sectionHeader(output, 'Exceptions') formatter.listHeader(output, listHeader) exception_names = function.getExceptionNames() exception_names.sort() #output_reduced_name = output.name[len(self.getDocsetBaseDirectory())+1:] output_buffer = StringIO() for name in exception_names: exception_class = self.getClassInfo(name) if exception_class: ref = formatter.getReference( exception_class, #output_reduced_name, output.name, ) else: ref = formatter.getPythonReference( name ) #output_buffer.write('%s\n' % ref) formatter.listItem(output, ref) #formatter.writeCode(output_buffer.getvalue(), output) formatter.listFooter(output) formatter.sectionFooter(output) formatter.popSectionLevel(output) return def _writeFunction(self, function_name, getInfo, output): "Output the documentation for the function in the parent object." function = getInfo(function_name) # # Header # self._formatter.itemHeader( output, function ) # # Function signature # self._writeFunctionSignature( function, output ) # # Docstring # self._formatter.writeText( function.getDocString(), output, function.getDocStringFormat() ) # # Exceptions # exception_names = function.getExceptionNames() if exception_names: self._writeExceptionListForFunction(output, function, None) return class MultiFileDocsetUnitTest(happydoclib.StreamFlushTest.StreamFlushTest): def testIgnorePackageReadme(self): filename = os.path.join('TestCases', 'test_package_summaries', 'FromReadmeTxt') import happydoclib.formatter.formatter_Null import happydoclib.parseinfo docset = MultiFileDocSet( formatterFactory=happydoclib.formatter.formatter_Null.NullFormatter, parserFunc=happydoclib.parseinfo.getDocs, defaultParserConfigValues={'docStringFormat':'StructuredText'}, inputModuleNames=[ filename ], outputBaseDirectory=self.output_dir, descriptionFilename='-', #descriptionFilename='README.txt', ) buffer = StringIO() docset._writeDescription( buffer ) assert not buffer.getvalue(), 'Wrote a description file when should not have.' return def testModuleOutputFileCalculation(self): filename = os.path.join('TestCases', 'test.py') import happydoclib.formatter.formatter_Null import happydoclib.parseinfo docset = MultiFileDocSet( formatterFactory=happydoclib.formatter.formatter_Null.NullFormatter, parserFunc=happydoclib.parseinfo.getDocs, defaultParserConfigValues={'docStringFormat':'StructuredText'}, inputModuleNames=[ filename ], outputBaseDirectory=self.output_dir, docsetBaseDirectory=os.path.join(self.output_dir, 'TestCases'), descriptionFilename='-', ) info_obj = docset[0] actual_output_name = docset.getFullOutputNameForObject(info_obj) expected_output_name = os.path.join(self.output_dir, 'TestCases', 'test.html') self.failUnlessEqual( actual_output_name, expected_output_name, ('Outputs do not match:\n' 'Got: %s\n' 'Expected: %s' % (actual_output_name, expected_output_name, ) ) ) return def testPackageOutputFileCalculation(self): filename = os.path.join('TestCases', 'test.py') import happydoclib.formatter.formatter_Null import happydoclib.parseinfo docset = MultiFileDocSet( formatterFactory=happydoclib.formatter.formatter_Null.NullFormatter, parserFunc=happydoclib.parseinfo.getDocs, defaultParserConfigValues={'docStringFormat':'StructuredText'}, inputModuleNames=[ filename ], outputBaseDirectory=self.output_dir, descriptionFilename='-', #descriptionFilename='README.txt', ) info_obj = None actual_output_name = docset.getFullOutputNameForObject(info_obj) expected_output_name = os.path.join(self.output_dir, 'index.html') self.failUnlessEqual( actual_output_name, expected_output_name, 'Outputs do not match:\n %s\nvs.\n %s' % (actual_output_name, expected_output_name, ) ) return