|
From: Doug H. <dou...@us...> - 2002-12-29 17:33:20
|
Update of /cvsroot/happydoc/HappyDoc3/happydoclib/docset
In directory sc8-pr-cvs1:/tmp/cvs-serv9352/happydoclib/docset
Modified Files:
docset_MultiHTMLFile.py
Log Message:
Let the PackageTree deal with finding subnodes by mimetype.
API cleanup to remove _ prefix from several methods which are part of
the API to override.
API change from writeX to processX for mimetype writers.
Add methods to document classes.
Index: docset_MultiHTMLFile.py
===================================================================
RCS file: /cvsroot/happydoc/HappyDoc3/happydoclib/docset/docset_MultiHTMLFile.py,v
retrieving revision 1.12
retrieving revision 1.13
diff -C2 -d -r1.12 -r1.13
*** docset_MultiHTMLFile.py 28 Dec 2002 15:59:51 -0000 1.12
--- docset_MultiHTMLFile.py 29 Dec 2002 17:33:17 -0000 1.13
***************
*** 56,59 ****
--- 56,60 ----
#
import os
+ import pprint
try:
from cStringIO import StringIO
***************
*** 114,118 ****
)
! if packageTreeNode.values():
#
# This is a directory.
--- 115,119 ----
)
! if packageTreeNode.getMimeType() == ('application/x-directory', None):
#
# This is a directory.
***************
*** 128,131 ****
--- 129,147 ----
return filename_with_extension
+ def getOutputFilenameForSymbol(self, packageTreeNode, symbolName, includePath=1):
+ """Returns a filename where documentation for symbolName should be written.
+
+ The filename will be in the output directory, possibly in a
+ subdirectory based on the path from the input root to the
+ input file.
+ """
+ package_output_name = self.getOutputFilenameForPackageTreeNode(
+ packageTreeNode,
+ includePath=includePath,
+ )
+ name, ext = os.path.splitext(package_output_name)
+ output_name = '%s_%s.html' % (name, symbolName)
+ return output_name
+
def writeFileHeader(self, output, title='', subtitle=''):
"""Given an open output stream, write a header using the title and subtitle.
***************
*** 193,197 ****
return
! def _writeDescriptiveList(self, output, descriptiveList):
"""Write a list including descriptions.
--- 209,213 ----
return
! def writeDescriptiveList(self, output, descriptiveList):
"""Write a list including descriptions.
***************
*** 205,209 ****
"""
! output.write('<!-- _writeDescriptiveList -->\n')
output.write('<table border="0" cellpadding="3" cellspacing="0">\n')
--- 221,225 ----
"""
! output.write('<!-- writeDescriptiveList -->\n')
output.write('<table border="0" cellpadding="3" cellspacing="0">\n')
***************
*** 225,228 ****
--- 241,246 ----
def writeList(self, output, listElements):
+ """Write a formatted list of values to the output.
+ """
output.write('<p>\n')
for list_element in listElements:
***************
*** 262,266 ****
return href
! def _getAnchorTagForPackageTreeNode(self, source, destination, title=None):
"""Return a anchor tag to be included in the documentation of
source that points to the destination.
--- 280,288 ----
return href
! def _getAnchorTagForPackageTreeNode(self,
! source,
! destination,
! title=None,
! internalTarget=None):
"""Return a anchor tag to be included in the documentation of
source that points to the destination.
***************
*** 269,275 ****
--- 291,301 ----
title = destination.getName()
href = self._computeRelativeHREF(source, destination)
+ if internalTarget:
+ href='%s#%s' % (href, internalTarget)
return '<a href="%s">%s</a>' % (href, title)
def writeSectionTitle(self, output, title, subtitle, anchor=None):
+ """Generate the text and styles to begin a new section.
+ """
bgcolor = self.levelTwoHeadingBackgroundColor
fgcolor = self.levelTwoHeadingForegroundColor
***************
*** 301,305 ****
def pushSectionLevel(self, output, title, subtitle='', anchor=''):
! """Generate the text and styles to begin a new section one deeper than the previous level.
"""
output.write(
--- 327,334 ----
def pushSectionLevel(self, output, title, subtitle='', anchor=''):
! """Increase the section level.
!
! Generate the text and styles to begin a new section one
! deeper than the previous level.
"""
output.write(
***************
*** 314,326 ****
def writeSectionFooter(self, output):
output.write('</td></tr>\n')
return
def popSectionLevel(self, output):
self.writeSectionFooter(output)
output.write('</table>')
return
! def _writeTOCReferencesSection(self,
output,
packageTreeNode,
--- 343,362 ----
def writeSectionFooter(self, output):
+ """Generate the text and styles to close the current section.
+ """
output.write('</td></tr>\n')
return
def popSectionLevel(self, output):
+ """Decrease the section level.
+
+ Generate the text and styles to close the current section
+ and change the section level to the next higher level.
+ """
self.writeSectionFooter(output)
output.write('</table>')
return
! def writeTOCReferencesSection(self,
output,
packageTreeNode,
***************
*** 344,353 ****
"""
descriptive_list = [(self._getAnchorTagForPackageTreeNode(packageTreeNode, node), ) + node.getSummaryAndFormat()
! for name, node in moduleList ]
if descriptive_list:
self.pushSectionLevel(output, title)
descriptive_list.sort()
! self._writeDescriptiveList(output, descriptive_list)
if descriptive_list:
--- 380,390 ----
"""
descriptive_list = [(self._getAnchorTagForPackageTreeNode(packageTreeNode, node), ) + node.getSummaryAndFormat()
! for node in moduleList
! ]
if descriptive_list:
self.pushSectionLevel(output, title)
descriptive_list.sort()
! self.writeDescriptiveList(output, descriptive_list)
if descriptive_list:
***************
*** 386,406 ****
pass
else:
! self._writePythonFileInfoToOutput(output, init_node)
!
! #
! # Group contained modules by mimetype
! #
! contained_modules = packageTreeNode.items()
! contained_modules_map = {}
!
! for name, node in contained_modules:
! mimetype, encoding = node.getMimeType()
! set = contained_modules_map.setdefault(mimetype, [])
! set.append( (name, node) )
!
! #output.write('Summary\n')
! #descriptive_list = [ (name, str(len(set)), 'StructuredText') for name, set in contained_modules_map.items() ]
! #descriptive_list.sort()
! #self._writeDescriptiveList(output, descriptive_list)
#
--- 423,427 ----
pass
else:
! self.writePythonFileInfoToOutput(output, init_node)
#
***************
*** 408,416 ****
# converted.
#
! plain_text_files = contained_modules_map.get('text/plain', [])
! structured_text_files = contained_modules_map.get('text/x-structured', [])
! html_files = contained_modules_map.get('text/html', [])
text_files = plain_text_files + structured_text_files + html_files
! self._writeTOCReferencesSection(
output,
packageTreeNode,
--- 429,437 ----
# converted.
#
! plain_text_files = packageTreeNode.getSubNodes('text/plain')
! structured_text_files = packageTreeNode.getSubNodes('text/x-structured')
! html_files = packageTreeNode.getSubNodes('text/html')
text_files = plain_text_files + structured_text_files + html_files
! self.writeTOCReferencesSection(
output,
packageTreeNode,
***************
*** 422,431 ****
# Write out references to Python files we parsed.
#
! self._writeTOCReferencesSection(
output,
packageTreeNode,
'Python files',
! [ cm for cm in contained_modules_map.get('text/x-python', [])
! if cm[1].getName() != '__init__.py'
],
)
--- 443,452 ----
# Write out references to Python files we parsed.
#
! self.writeTOCReferencesSection(
output,
packageTreeNode,
'Python files',
! [ node for node in packageTreeNode.getSubNodes('text/x-python')
! if node.getName() != '__init__.py'
],
)
***************
*** 434,442 ****
# Write out references to subdirectories
#
! directories = contained_modules_map.get('application/x-directory', [])
#directories = [ d for d in directories
# if d[1].items()
# ]
! self._writeTOCReferencesSection(
output,
packageTreeNode,
--- 455,463 ----
# Write out references to subdirectories
#
! directories = packageTreeNode.getSubNodes('application/x-directory')
#directories = [ d for d in directories
# if d[1].items()
# ]
! self.writeTOCReferencesSection(
output,
packageTreeNode,
***************
*** 450,454 ****
return
! def _writeImportWithFrom(self, output, pacakgeTreeNode, moduleReference, symbolReferences):
output.write('from %s import %s<br>' % (moduleReference,
', '.join(symbolReferences),
--- 471,477 ----
return
! def writeImportWithFrom(self, output, pacakgeTreeNode, moduleReference, symbolReferences):
! """Write an import statement: 'from X import Y'
! """
output.write('from %s import %s<br>' % (moduleReference,
', '.join(symbolReferences),
***************
*** 457,465 ****
return
! def _writeImport(self, output, packageTreeNode, moduleReference):
output.write('import %s<br>' % moduleReference)
return
! def _writeImportForPythonSystemModule(self,
output,
packageTreeNode,
--- 480,490 ----
return
! def writeImport(self, output, packageTreeNode, moduleReference):
! """Write an import statement: 'import X'
! """
output.write('import %s<br>' % moduleReference)
return
! def writeImportForPythonSystemModule(self,
output,
packageTreeNode,
***************
*** 468,474 ****
url,
):
ref = '<a href="%s">%s</a>' % (url, name)
if symbols:
! self._writeImportWithFrom(output,
packageTreeNode,
ref,
--- 493,505 ----
url,
):
+ """Write an import statement for a Python system module.
+
+ Handles either 'from X import Y' or 'import X'. The module
+ name is a link to the Python documentation on
+ http://www.python.org.
+ """
ref = '<a href="%s">%s</a>' % (url, name)
if symbols:
! self.writeImportWithFrom(output,
packageTreeNode,
ref,
***************
*** 476,480 ****
)
else:
! self._writeImport(output,
packageTreeNode,
ref,
--- 507,511 ----
)
else:
! self.writeImport(output,
packageTreeNode,
ref,
***************
*** 483,487 ****
! def _writeImportForKnownModule(self,
output,
packageTreeNode,
--- 514,518 ----
! def writeImportForKnownModule(self,
output,
packageTreeNode,
***************
*** 490,493 ****
--- 521,530 ----
symbols,
):
+ """Write an import statement for a module known to HappyDoc.
+
+ Handles either 'from X import Y' or 'import X'. The module
+ name is a link to the documentation for that module within the
+ HappyDoc-generated output.
+ """
#
# Compute the href from here to there.
***************
*** 515,519 ****
symbol_refs.append( symbol_ref )
! self._writeImportWithFrom(output,
packageTreeNode,
ref,
--- 552,556 ----
symbol_refs.append( symbol_ref )
! self.writeImportWithFrom(output,
packageTreeNode,
ref,
***************
*** 521,525 ****
)
else:
! self._writeImport(output,
packageTreeNode,
ref,
--- 558,562 ----
)
else:
! self.writeImport(output,
packageTreeNode,
ref,
***************
*** 528,532 ****
! def _writePythonFileImportsToOutput(self, output, packageTreeNode):
"""Writes the list of imported modules for the packageTreeNode.
"""
--- 565,569 ----
! def writePythonFileImportsToOutput(self, output, packageTreeNode):
"""Writes the list of imported modules for the packageTreeNode.
"""
***************
*** 545,549 ****
url = getPythonSystemModuleURL(name)
if url:
! self._writeImportForPythonSystemModule(output,
packageTreeNode,
name,
--- 582,586 ----
url = getPythonSystemModuleURL(name)
if url:
! self.writeImportForPythonSystemModule(output,
packageTreeNode,
name,
***************
*** 558,562 ****
referenced_module = packageTreeNode.findNodeFromDottedName(name)
if referenced_module is not None:
! self._writeImportForKnownModule(output,
packageTreeNode,
name,
--- 595,599 ----
referenced_module = packageTreeNode.findNodeFromDottedName(name)
if referenced_module is not None:
! self.writeImportForKnownModule(output,
packageTreeNode,
name,
***************
*** 570,574 ****
#
if symbols:
! self._writeImportWithFrom(output,
packageTreeNode,
name,
--- 607,611 ----
#
if symbols:
! self.writeImportWithFrom(output,
packageTreeNode,
name,
***************
*** 576,580 ****
)
else:
! self._writeImport(output,
packageTreeNode,
name,
--- 613,617 ----
)
else:
! self.writeImport(output,
packageTreeNode,
name,
***************
*** 587,591 ****
return
! def _writePreformatted(self, output, text):
"""Write text as a preformatted section.
"""
--- 624,628 ----
return
! def writePreformatted(self, output, text):
"""Write text as a preformatted section.
"""
***************
*** 597,601 ****
return
! def _writeFunctionParameter(self, output, name, info):
'''Write a function parameter to the output.
--- 634,638 ----
return
! def writeFunctionParameter(self, output, name, info):
'''Write a function parameter to the output.
***************
*** 636,640 ****
return
! def _writeFunctionSignature(self,
output,
packageTreeNode,
--- 673,677 ----
return
! def writeFunctionSignature(self,
output,
packageTreeNode,
***************
*** 661,665 ****
param_info = function.getParameterInfo(param)
signature_buffer.write(' ')
! self._writeFunctionParameter(signature_buffer,
param,
param_info,
--- 698,702 ----
param_info = function.getParameterInfo(param)
signature_buffer.write(' ')
! self.writeFunctionParameter(signature_buffer,
param,
param_info,
***************
*** 674,678 ****
signature_buffer.write(' ' * indent)
param_info = function.getParameterInfo(param)
! self._writeFunctionParameter(signature_buffer,
param,
param_info,
--- 711,715 ----
signature_buffer.write(' ' * indent)
param_info = function.getParameterInfo(param)
! self.writeFunctionParameter(signature_buffer,
param,
param_info,
***************
*** 682,689 ****
signature_buffer.write(')\n')
! self._writePreformatted(output, signature_buffer.getvalue())
return
! def _writeExceptionListForFunction(self, output, function):
"""Write the list of exceptions raised by a function.
--- 719,726 ----
signature_buffer.write(')\n')
! self.writePreformatted(output, signature_buffer.getvalue())
return
! def writeExceptionListForFunction(self, output, function):
"""Write the list of exceptions raised by a function.
***************
*** 711,714 ****
--- 748,753 ----
if exception_class:
+ # FIXME - Need a way to get a reference to a class in the
+ # scanned input!
ref = formatter.getReference( exception_class,
#output_reduced_name,
***************
*** 727,735 ****
return
! def _writeOneFunctionToOutput(self,
output,
packageTreeNode,
functionInfo,
):
self.pushSectionLevel(output,
title='',
--- 766,776 ----
return
! def writeOneFunctionToOutput(self,
output,
packageTreeNode,
functionInfo,
):
+ """Write all of the information for one function to the output stream.
+ """
self.pushSectionLevel(output,
title='',
***************
*** 740,744 ****
# Signature
#
! self._writeFunctionSignature(output, packageTreeNode, functionInfo)
#
--- 781,785 ----
# Signature
#
! self.writeFunctionSignature(output, packageTreeNode, functionInfo)
#
***************
*** 752,761 ****
# Exceptions
#
! self._writeExceptionListForFunction(output, functionInfo)
self.popSectionLevel(output)
return
! def _writeFunctionsToOutput(self, output, packageTreeNode):
"""Writes information about functions in this module to the output stream.
"""
--- 793,802 ----
# Exceptions
#
! self.writeExceptionListForFunction(output, functionInfo)
self.popSectionLevel(output)
return
! def writeFunctionsToOutput(self, output, packageTreeNode):
"""Writes information about functions in this module to the output stream.
"""
***************
*** 777,781 ****
for function_name in function_names:
! self._writeOneFunctionToOutput(
output,
packageTreeNode,
--- 818,822 ----
for function_name in function_names:
! self.writeOneFunctionToOutput(
output,
packageTreeNode,
***************
*** 786,802 ****
return
! def _writePythonFileInfoToOutput(self, output, packageTreeNode):
"""Writes parts of the Python file information to the output stream.
"""
! self._writePythonFileImportsToOutput(output, packageTreeNode)
! self._writeFunctionsToOutput(output, packageTreeNode)
! # Classes
return
! def writePythonFile(self, packageTreeNode):
"""Handler for text/x-python nodes.
"""
! trace.into('MultiHTMLFileDocSet', 'writePythonFile',
packageTreeNode=packageTreeNode,
)
--- 827,1003 ----
return
! def _getBaseClassTree(self, packageTreeNode, className):
! try:
! class_info = packageTreeNode.module_info.getClassInfo(className)
! except KeyError:
! base_class_names = []
! else:
! base_class_names = self._filterNames(class_info.getBaseClassNames())
!
! base_class_trees = []
! for base_class_name in base_class_names:
! base_class_tree = self._getBaseClassTree(packageTreeNode,
! base_class_name,
! )
! base_class_trees.append( base_class_tree )
!
! try:
! symbol_info = packageTreeNode.module_info.getClassInfo(className)
! except KeyError:
! ref = className
! else:
! symbol_output_name = self.getOutputFilenameForSymbol(
! packageTreeNode,
! className,
! includePath=0,
! )
! ref = '<a href="%s">%s</a>' % (symbol_output_name, className)
!
! return (ref, base_class_trees)
!
! def writeTree(self, output, treeRoot, indent=0):
! output.write('%s%s<br>' % (' ' * indent, treeRoot[0]))
! for subtree in treeRoot[1]:
! self.writeTree(output, subtree, indent+1)
! return
!
! def writeBaseClassNames(self, output, packageTreeNode, classInfo):
! base_class_tree = self._getBaseClassTree(packageTreeNode, classInfo.getName())
! #self.writeList(output, base_class_names)
! output.write('<p>\n')
! self.writeTree(output, base_class_tree)
! output.write('</p>\n')
! return
!
! def writeOneClassToOutput(self, output, packageTreeNode, className):
! """Writes information about one class to the output stream.
! """
! class_info = packageTreeNode.module_info.getClassInfo(className)
!
! #
! # Description
! #
! docstring_text = class_info.getDocString()
! docstring_format = class_info.getDocStringFormat()
! self.writeText(output, docstring_text, docstring_format)
!
! #
! # Base classes
! #
! base_class_names = self._filterNames(class_info.getBaseClassNames())
! if base_class_names:
! self.pushSectionLevel(output, 'Base Classes')
! self.writeBaseClassNames(output, packageTreeNode, class_info)
! self.popSectionLevel(output)
!
! #
! # Methods
! #
! method_names = self._filterNames(class_info.getMethodNames())
! if method_names:
! if self.sort_names:
! method_names.sort()
! self.pushSectionLevel(output, 'Methods')
!
! for method_name in method_names:
! method_info = class_info.getMethodInfo(method_name)
! self.writeOneFunctionToOutput(
! output,
! packageTreeNode,
! method_info,
! )
!
! self.popSectionLevel(output)
!
! return
!
! def writeClassListForModule(self, output, packageTreeNode):
! """Write descriptions of all of the classes to the output stream.
! """
! class_names = self._filterNames(packageTreeNode.module_info.getClassNames())
!
! if self.sort_names:
! class_names.sort()
!
! descriptive_list = []
!
! for class_name in class_names:
! symbol_output_name = self.getOutputFilenameForSymbol(
! packageTreeNode,
! class_name,
! includePath=0,
! )
! ref = '<a href="%s">%s</a>' % (symbol_output_name, class_name)
! class_info = packageTreeNode.module_info.getClassInfo(class_name)
! class_info_summary, class_info_format = class_info.getSummaryAndFormat()
! descriptive_list.append( (ref, class_info_summary, class_info_format) )
!
! self.pushSectionLevel(output, 'Classes')
! self.writeDescriptiveList(output, descriptive_list)
! self.popSectionLevel(output)
! return
!
! def writeClassesToOutput(self, output, packageTreeNode):
! """Writes information about classes in this module to the output stream.
! """
! class_names = self._filterNames(packageTreeNode.module_info.getClassNames())
! if not class_names:
! return
!
! #
! # Write a list of the classes to the current output file
! #
! self.writeClassListForModule(output, packageTreeNode)
!
! #
! # Document each class in its own file
! #
!
! for class_name in class_names:
!
! #
! # Open a new output stream for the class.
! #
! class_output_name = self.getOutputFilenameForSymbol(
! packageTreeNode,
! class_name,
! includePath=1,
! )
!
! class_output = self.openOutput(
! class_output_name,
! title=self.title,
! subtitle='Class: %s' % class_name,
! )
!
! #
! # Write class documentation
! #
! self.writeOneClassToOutput(
! class_output,
! packageTreeNode,
! class_name,
! )
!
! #
! # Close the class' output stream
! #
! self.closeOutput(class_output)
!
! return
!
! def writePythonFileInfoToOutput(self, output, packageTreeNode):
"""Writes parts of the Python file information to the output stream.
"""
! self.writePythonFileImportsToOutput(output, packageTreeNode)
! self.writeFunctionsToOutput(output, packageTreeNode)
! self.writeClassesToOutput(output, packageTreeNode)
return
! def processPythonFile(self, packageTreeNode):
"""Handler for text/x-python nodes.
"""
! trace.into('MultiHTMLFileDocSet', 'processPythonFile',
packageTreeNode=packageTreeNode,
)
***************
*** 804,807 ****
--- 1005,1009 ----
node_name = packageTreeNode.getName()
if node_name == '__init__.py':
+
#
# Skip the __init__.py file, since it will
***************
*** 834,838 ****
self.writeText(output, readme_text, text_format)
! self._writePythonFileInfoToOutput(output, packageTreeNode)
self.closeOutput(output)
--- 1036,1040 ----
self.writeText(output, readme_text, text_format)
! self.writePythonFileInfoToOutput(output, packageTreeNode)
self.closeOutput(output)
|
