# # FILE $Id: ParseCollect.py,v 1.8 1996/09/06 09:58:44 omfadmin Exp $ # # DESCRIPTION Collect doctrings from Python modules, and generate Manual page. # # AUTHOR SEISY/LKSB Daniel Larsson # # 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 ABB Industrial Systems # not be used in advertising or publicity pertaining to # distribution of the software without specific, written prior permission. # # ABB INDUSTRIAL SYSTEMS DISCLAIMS ALL WARRANTIES WITH REGARD TO # THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND # FITNESS, IN NO EVENT SHALL ABB INDUSTRIAL SYSTEMS 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. # # Copyright (C) ABB Industrial Systems AB, 1996 # Unpublished work. All Rights Reserved. # # HISTORY: $Log: /Gendoc/ParseCollect.py $ # # 1 98-04-01 13:15 Daniel # Revision 1.8 1996/09/06 09:58:44 omfadmin # Replaced setext markup with structured text markup. # # Revision 1.7 1996/08/26 20:37:17 omfadmin # Removed unnecessary code. # # Revision 1.6 1996/07/11 16:45:59 omfadmin # Moved docstring parsing code to the new docutil module. # # Revision 1.5 1996/07/10 03:14:27 omfadmin # Changed definition of __version__. # # Revision 1.4 1996/07/08 05:17:55 omfadmin # Fixed handling of bullet lists. # The hook method module() is now called file_input since # Fred Drake's changes. # # Revision 1.3 1996/06/24 09:54:16 omfadmin # Added support for setext style hyperlinks. # Fixed bug in _stripleadingtabs (Removed internal whitespace too, sometimes!). # Previously I forgot doing setext substitution and paragraph splitting # on function docstrings. That has been corrected. # # Revision 1.2 1996/06/21 00:04:01 omfadmin # - Improved docstrings # - Only include modules imported at global scope # - Added list of global functions in synopsis for module # - Optionally skip ~internal~ names (beginning with single '_') # # Revision 1.1 1996/06/13 17:52:11 omfadmin # Initial revision # # """Generates manual pages from Python source code. This module defines classes that traverse a Python source file and generates manual pages in an abstract form. These pages can then be rendered in various formats. """ __version__ = "$Revision: 1 $" import regex import string import ASTWalker import symbol import ManualPage import docutil VERBOSE = 0 def message(string, level=1): if VERBOSE >= level: print string class ScopeTracker(ASTWalker.ASTWalker): """Keeps track of the declaration scope. To figure out to what class/function a function belongs, this AST walker keeps a stack of declarations while trodding along the tree. The stack is available as ~self.decl_stack~, where each element is a list [node, level]. In subclasses, be sure to call this class' ~classdef~ and ~funcdef~ methods to push them on the stack.""" def __init__(self, node_builder=None): ASTWalker.ASTWalker.__init__(self, node_builder) # Python indent level is used to figure out # when a class declaration ends, etc. self.indent = 0 self.decl_stack = [] def is_global(self): """Returns true if we are at the global scope""" return len(self.decl_stack) == 0 def top_declaration(self): """Return topmost declaration.""" return self.decl_stack[-1] # Overridden methods from base class def classdef(self, ref_classdef): """Override this to handle class definition nodes.""" # Push class and indentation level on declaration stack self.decl_stack.append([ref_classdef, self.indent]) message(' '*self.indent + ref_classdef.name, 2) def funcdef(self, ref_funcdef): """Override this to handle function definition nodes.""" # Push function and indentation level on declaration stack self.decl_stack.append([ref_funcdef, self.indent]) message(' '*self.indent + ref_funcdef.name, 2) def indent(self, ref_indent): """Override this to handle indent nodes.""" message(' '*self.indent + '>', 2) self.indent = self.indent+1 def dedent(self, ref_dedent): """Override this to handle dedent nodes.""" self.indent = self.indent-1 message(' '*self.indent + '<', 2) # Check if topmost declaration on stack is finished if len(self.decl_stack) > 0 and self.decl_stack[-1][1] == self.indent: top, self.decl_stack = self.decl_stack[-1], self.decl_stack[:-1] return top else: return None def _manpage_init(manpage, type_str, name, doc, marker=None): title = type_str + ' ' + name if doc: doc = eval(doc) # doc is a string containing a string! oneliner, doc = docutil.split_doc(doc) if oneliner: title = title + ' - ' + oneliner args = (title, name+', '+type_str,) if marker: args = args + (marker,) apply(manpage.title, args) synopsis = manpage.section('SYNOPSIS') # Write module description description = manpage.section('DESCRIPTION') if doc: docutil.docregex_parse(manpage, description, doc) see_also = manpage.section('SEE ALSO') class ParseCollector(ScopeTracker): """Collect docstrings from parse tree. Traverses a module's abstract syntax tree (AST), collects docstrings, and generates manual pages. To use this class you must have Fred Drake's parser module built into your python interpreter. To get the AST of a module, do something like this: > import parser > module = open(module_file).read() > ast_tuple = parser.ast2tuple(parser.suite(module)) To generate a set of manual pages, you create a ~ParseCollector~ and let it walk the tree: > module_name = splitfields(basename(module_file), '.')[0] > pc = ParseCollector(module_name) > manpages = pc.walk(ast_tuple) To generate manual pages, create a formatter for a particular output format: > import ManFormatter > html = ManFormatter.HTMLFormatter() > for manpage in manpages: > text = manpage.render(html) > file = open(manpage.name() + html.file_ext, 'w') > file.write(text) > file.close() > # Voila! """ def __init__(self, module_name, skip_internal=1, node_builder=None): """Constructor. ~module_name~ is the python module name to parse. If ~skip_internal~ is set, names beginning with a single '_' are skipped (conventionally they are treated as non-public objects). _ADVANCED_: ~node_builder~ allows you to use a custom node builder when traversing the AST. I have no idea why you would want to do that ;-).""" ScopeTracker.__init__(self, node_builder) # Python indent level is used to figure out # when a class declaration ends, etc. self.indent = 0 self.name = module_name self.skip_internal = skip_internal def walk(self, ast): """Walk the ast and generate manual pages. Walks ~ast~ and generates a list of manual pages, one for the module, and one for each class in the module.""" self.manpage = ManualPage.ManualPage(self.name) self.classes = [] self.functions = [] self.see_also = [] self.manpgs = [self.manpage] ASTWalker.ASTWalker.walk(self, ast) synopsis = self.manpage.section('SYNOPSIS') if self.classes: code = '# Classes\n' + string.joinfields(self.classes, '\n') self.manpage.code(code, synopsis) if self.functions: code = '# Functions\n' + string.joinfields(self.functions, '\n') self.manpage.code(code, synopsis) if self.see_also: # Get reference to the "SEE ALSO" section see_also = self.manpage.section('SEE ALSO') # Spit out the text into the "SEE ALSO" section list = map(self.manpage.reference, self.see_also) list = string.joinfields(list, ', ') self.manpage.paragraph(list, see_also) return self.manpgs def render(self, formatter): """Render manual pages. ~formatter~ is an instance (or a sequence of instances) capable of formatting a ManualPage into some format. Formatters are available for at least HTML, FrameMaker MIF and ASCII.""" try: formatter[0] except: formatter = [formatter] for form in formatter: for manpage in self.manpgs: file = open(manpage.name()+form.file_ext, 'w') file.write(manpage.render(form)) file.close() # Overridden methods from base class def file_input(self, ref_module): """Handles module nodes. Each module is put in a separate file.""" message("*** Start handling %s" % self.name) if ref_module: _manpage_init(self.manpage, type_str = 'module', name = self.name, doc = ref_module.doc) # Navigation button to module index page self.manpage.top('index.html') def import_stmt(self, ref_import): """Handles import nodes. Each import on global level ends up in the SEE ALSO section.""" message("--- Import stmnt %s" % ref_import.name) # Create a hyperlink reference if self.is_global() and ref_import.name not in self.see_also: self.see_also.append(ref_import.name) def classdef(self, ref_classdef): """ Override this to handle class definition nodes. """ message("--- Class def %s" % ref_classdef.name) # Only generate doc for classes in the global scope is_global = self.is_global() # Skip ~internal~ classes, maybe? if self.skip_internal and ref_classdef.name[0] == '_': is_global = 0 if is_global: ref = self.name + '-' + ref_classdef.name text = self.manpage.reference(ref, str(ref_classdef)[:-1]) self.classes.append(text) # Push my declaration on stack ScopeTracker.classdef(self, ref_classdef) if is_global: manpage = ManualPage.ManualPage(self.name + '-' + ref_classdef.name) marker = self.name+', module' _manpage_init(manpage, type_str = 'class', name = ref_classdef.name, doc = ref_classdef.doc, marker = marker) # Set up link to module page manpage.top(self.manpage) decl = self.top_declaration() decl.append(manpage) decl.append(str(ref_classdef)) def funcdef(self, ref_funcdef): """ Override this to handle function definition nodes. """ message("--- Func def %s" % ref_funcdef.name) # Unless skip_internal is false, skip functions # beginning with a single underscore. if not self.skip_internal or \ ref_funcdef.name[0] != '_' or \ ref_funcdef.name[1] == '_': doc = ref_funcdef.doc if doc: doc = eval(doc) # doc is a string containing a string! oneliner, doc = docutil.split_doc(doc) signature = str(ref_funcdef)[:-1] manpage = self.manpage # Create hyperlink if it has a docstring (apart from the # oneliner). if doc: ref_signature = manpage.reference(signature) else: ref_signature = signature if self.is_global(): self.functions.append(ref_signature) mark_mod = self.name + ', module' else: top = self.top_declaration() # Is this a member function of a global function? if top[0].ast[0] == symbol.classdef and len(top) > 2: # Yes, insert the function in the class # declaration element on the stack. The manpage # is updated when we reach the end of the # class' scope. manpage = top[2] top.append(ref_signature) if oneliner: top.append(' # '+oneliner) mark_mod = top[0].name + ', class' # If we have a doc string, generate a hyperlink # to it, and put the oneliner with the function # declaration. if doc: mark_me = ref_funcdef.name + ', function' description = manpage.section('DESCRIPTION') fundesc = manpage.section(signature, description, mark_me, mark_mod) docutil.docregex_parse(manpage, fundesc, doc) #manpage.paragraph(doc, fundesc) ScopeTracker.funcdef(self, ref_funcdef) def dedent(self, ref_dedent): """ Override this to handle dedent nodes. """ top = ScopeTracker.dedent(self, ref_dedent) if top and len(top) > 2: manpage = top[2] synopsis = manpage.section('SYNOPSIS') # If it is a classdef, collect the member function # strings and put them in the manual page. if top[0].ast[0] == symbol.classdef: decl_str = string.joinfields(top[3:], '\n ') manpage.code(decl_str, synopsis) self.manpgs.append(manpage)