From 8f7d17bfe336f1fa0ea0fa335f974993420c6333 Mon Sep 17 00:00:00 2001 From: Werner Lemberg Date: Wed, 28 May 2008 06:39:33 +0000 Subject: [PATCH] formatting --- src/tools/docmaker/content.py | 76 +++++++++++++++------------------ src/tools/docmaker/docbeauty.py | 8 ++-- src/tools/docmaker/docmaker.py | 5 +-- src/tools/docmaker/formatter.py | 5 +-- src/tools/docmaker/sources.py | 14 +++--- src/tools/docmaker/tohtml.py | 43 ++++++------------- src/tools/docmaker/utils.py | 3 +- 7 files changed, 63 insertions(+), 91 deletions(-) diff --git a/src/tools/docmaker/content.py b/src/tools/docmaker/content.py index d751c2102..f297e8edc 100644 --- a/src/tools/docmaker/content.py +++ b/src/tools/docmaker/content.py @@ -45,7 +45,7 @@ re_identifier = re.compile( r'(\w*)' ) # The object is filled line by line by the parser; it strips the leading # "margin" space from each input line before storing it in 'self.lines'. # -class DocCode: +class DocCode: def __init__( self, margin, lines ): self.lines = [] @@ -57,15 +57,15 @@ class DocCode: l = l[margin:] self.lines.append( l ) - def dump( self, prefix = "", width=60 ): + def dump( self, prefix = "", width = 60 ): lines = self.dump_lines( 0, width ) for l in lines: print prefix + l - def dump_lines( self, margin=0, width=60 ): + def dump_lines( self, margin = 0, width = 60 ): result = [] for l in self.lines: - result.append( " "*margin + l ) + result.append( " " * margin + l ) return result @@ -76,7 +76,7 @@ class DocCode: # # 'self.words' contains the list of words that make up the paragraph # -class DocPara: +class DocPara: def __init__( self, lines ): self.lines = None @@ -90,7 +90,7 @@ class DocPara: for l in lines: print prefix + l - def dump_lines( self, margin=0, width = 60 ): + def dump_lines( self, margin = 0, width = 60 ): cur = "" # current line col = 0 # current width result = [] @@ -98,10 +98,10 @@ class DocPara: for word in self.words: ln = len( word ) if col > 0: - ln = ln+1 + ln = ln + 1 if col + ln > width: - result.append( " "*margin + cur ) + result.append( " " * margin + cur ) cur = word col = len( word ) else: @@ -111,7 +111,7 @@ class DocPara: col = col + ln if col > 0: - result.append( " "*margin + cur ) + result.append( " " * margin + cur ) return result @@ -123,17 +123,17 @@ class DocPara: # DocCode objects. Each DocField also has an optional "name" which is used # when the object corresponds to a field or value definition # -class DocField: +class DocField: def __init__( self, name, lines ): self.name = name # can be None for normal paragraphs/sources - self.items = [] # list of items + self.items = [] # list of items - mode_none = 0 # start parsing mode - mode_code = 1 # parsing code sequences - mode_para = 3 # parsing normal paragraph + mode_none = 0 # start parsing mode + mode_code = 1 # parsing code sequences + mode_para = 3 # parsing normal paragraph - margin = -1 # current code sequence indentation + margin = -1 # current code sequence indentation cur_lines = [] # now analyze the markup lines to see if they contain paragraphs, @@ -141,11 +141,10 @@ class DocField: # start = 0 mode = mode_none - for l in lines: + for l in lines: # are we parsing a code sequence ? if mode == mode_code: - m = re_code_end.match( l ) if m and len( m.group( 1 ) ) <= margin: # that's it, we finised the code sequence @@ -170,7 +169,6 @@ class DocField: # switch to code extraction mode margin = len( m.group( 1 ) ) mode = mode_code - else: if not string.split( l ) and cur_lines: # if the line is empty, we end the current paragraph, @@ -187,7 +185,6 @@ class DocField: # unexpected end of code sequence code = DocCode( margin, cur_lines ) self.items.append( code ) - elif cur_lines: para = DocPara( cur_lines ) self.items.append( para ) @@ -204,9 +201,10 @@ class DocField: p.dump( prefix ) first = 0 - def dump_lines( self, margin=0, width=60 ): + def dump_lines( self, margin = 0, width = 60 ): result = [] nl = None + for p in self.items: if nl: result.append( "" ) @@ -224,7 +222,7 @@ re_field = re.compile( r"\s*(\w*|\w(\w|\.)*\w)\s*::" ) -class DocMarkup: +class DocMarkup: def __init__( self, tag, lines ): self.tag = string.lower( tag ) @@ -248,7 +246,7 @@ class DocMarkup: field = m.group( 1 ) # record field name ln = len( m.group( 0 ) ) - l = " "*ln + l[ln:] + l = " " * ln + l[ln:] cur_lines = [l] else: cur_lines.append( l ) @@ -260,7 +258,6 @@ class DocMarkup: def get_name( self ): try: return self.fields[0].items[0].words[0] - except: return None @@ -270,19 +267,18 @@ class DocMarkup: for word in self.fields[0].items[0].words: result = result + " " + word return result[1:] - except: return "ERROR" def dump( self, margin ): - print " "*margin + "<" + self.tag + ">" + print " " * margin + "<" + self.tag + ">" for f in self.fields: f.dump( " " ) - print " "*margin + "" + print " " * margin + "" -class DocChapter: +class DocChapter: def __init__( self, block ): self.block = block @@ -298,7 +294,7 @@ class DocChapter: -class DocSection: +class DocSection: def __init__( self, name = "Other" ): self.name = name @@ -334,7 +330,7 @@ class DocSection: -class ContentProcessor: +class ContentProcessor: def __init__( self ): """initialize a block content processor""" @@ -395,7 +391,7 @@ class ContentProcessor: if m: found = string.lower( m.group( 1 ) ) prefix = len( m.group( 0 ) ) - line = " "*prefix + line[prefix:] # remove markup from line + line = " " * prefix + line[prefix:] # remove markup from line break # is it the start of a new markup section ? @@ -415,18 +411,18 @@ class ContentProcessor: def parse_sources( self, source_processor ): blocks = source_processor.blocks count = len( blocks ) - for n in range( count ): + for n in range( count ): source = blocks[n] if source.content: # this is a documentation comment, we need to catch # all following normal blocks in the "follow" list # follow = [] - m = n+1 + m = n + 1 while m < count and not blocks[m].content: follow.append( blocks[m] ) - m = m+1 + m = m + 1 doc_block = DocBlock( source, follow, self ) @@ -447,7 +443,7 @@ class ContentProcessor: section.reorder() chap.sections.append( section ) else: - sys.stderr.write( "WARNING: chapter '" + + sys.stderr.write( "WARNING: chapter '" + \ chap.name + "' in " + chap.block.location() + \ " lists unknown section '" + sec + "'\n" ) @@ -468,7 +464,7 @@ class ContentProcessor: -class DocBlock: +class DocBlock: def __init__( self, source, follow, processor ): processor.reset() @@ -498,15 +494,13 @@ class DocBlock: except: pass - # detect new section starts if self.type == "section": + # detect new section starts processor.set_section( self.name ) processor.section.add_def( self ) - - # detect new chapter elif self.type == "chapter": + # detect new chapter processor.add_chapter( self ) - else: processor.section.add_block( self ) @@ -524,7 +518,7 @@ class DocBlock: # now strip the leading and trailing empty lines from the sources start = 0 - end = len( source )-1 + end = len( source ) - 1 while start < end and not string.strip( source[start] ): start = start + 1 @@ -532,7 +526,7 @@ class DocBlock: while start < end and not string.strip( source[end] ): end = end - 1 - source = source[start:end+1] + source = source[start:end + 1] self.code = source diff --git a/src/tools/docmaker/docbeauty.py b/src/tools/docmaker/docbeauty.py index 0e58f6644..3ddf4a94a 100644 --- a/src/tools/docmaker/docbeauty.py +++ b/src/tools/docmaker/docbeauty.py @@ -55,10 +55,9 @@ def main( argv ): global output_dir try: - opts, args = getopt.getopt( sys.argv[1:], - "hb", + opts, args = getopt.getopt( sys.argv[1:], \ + "hb", \ ["help", "backup"] ) - except getopt.GetoptError: usage() sys.exit( 2 ) @@ -87,10 +86,13 @@ def main( argv ): file_list = make_file_list( args ) for filename in file_list: source_processor.parse_file( filename ) + for block in source_processor.blocks: beautify_block( block ) + new_name = filename + ".new" ok = None + try: file = open( new_name, "wt" ) for block in source_processor.blocks: diff --git a/src/tools/docmaker/docmaker.py b/src/tools/docmaker/docmaker.py index 906ba8849..1d9de9fbf 100644 --- a/src/tools/docmaker/docmaker.py +++ b/src/tools/docmaker/docmaker.py @@ -44,10 +44,9 @@ def main( argv ): global output_dir try: - opts, args = getopt.getopt( sys.argv[1:], - "ht:o:p:", + opts, args = getopt.getopt( sys.argv[1:], \ + "ht:o:p:", \ ["help", "title=", "output=", "prefix="] ) - except getopt.GetoptError: usage() sys.exit( 2 ) diff --git a/src/tools/docmaker/formatter.py b/src/tools/docmaker/formatter.py index e889ccca9..f62ce676c 100644 --- a/src/tools/docmaker/formatter.py +++ b/src/tools/docmaker/formatter.py @@ -14,7 +14,7 @@ from utils import * # used to output -- you guessed it -- HTML. # -class Formatter: +class Formatter: def __init__( self, processor ): self.processor = processor @@ -41,7 +41,7 @@ class Formatter: def add_identifier( self, name, block ): if self.identifiers.has_key( name ): # duplicate name! - sys.stderr.write( \ + sys.stderr.write( \ "WARNING: duplicate definition for '" + name + "' in " + \ block.location() + ", previous definition in " + \ self.identifiers[name].location() + "\n" ) @@ -155,7 +155,6 @@ class Formatter: pass def section_dump( self, section, section_filename = None ): - output = None if section_filename: output = open_output( section_filename ) diff --git a/src/tools/docmaker/sources.py b/src/tools/docmaker/sources.py index 2d133c495..7b1f6206e 100644 --- a/src/tools/docmaker/sources.py +++ b/src/tools/docmaker/sources.py @@ -34,11 +34,10 @@ import fileinput, re, sys, os, string ## note that the 'column' pattern must contain a group that will ## be used to "unbox" the content of documentation comment blocks ## -class SourceBlockFormat: +class SourceBlockFormat: def __init__( self, id, start, column, end ): """create a block pattern, used to recognize special documentation blocks""" - self.id = id self.start = re.compile( start, re.VERBOSE ) self.column = re.compile( column, re.VERBOSE ) @@ -199,7 +198,8 @@ re_source_keywords = re.compile( '''\\b ( typedef | ## (i.e. sources or ordinary comments with no starting ## markup tag) ## -class SourceBlock: +class SourceBlock: + def __init__( self, processor, filename, lineno, lines ): self.processor = processor self.filename = filename @@ -233,7 +233,6 @@ class SourceBlock: def location( self ): return "(" + self.filename + ":" + repr( self.lineno ) + ")" - # debugging only - not used in normal operations def dump( self ): if self.content: @@ -268,7 +267,7 @@ class SourceBlock: ## - normal sources lines, include comments ## ## -class SourceProcessor: +class SourceProcessor: def __init__( self ): """initialize a source processor""" @@ -296,23 +295,20 @@ class SourceProcessor: for line in fileinput.input( filename ): # strip trailing newlines, important on Windows machines! - if line[-1] == '\012': + if line[-1] == '\012': line = line[0:-1] if self.format == None: self.process_normal_line( line ) - else: if self.format.end.match( line ): # that's a normal block end, add it to lines and # create a new block self.lines.append( line ) self.add_block_lines() - elif self.format.column.match( line ): # that's a normal column line, add it to 'lines' self.lines.append( line ) - else: # humm.. this is an unexpected block end, # create a new block, but don't process the line diff --git a/src/tools/docmaker/tohtml.py b/src/tools/docmaker/tohtml.py index f8a78fb2e..e0cdf390a 100644 --- a/src/tools/docmaker/tohtml.py +++ b/src/tools/docmaker/tohtml.py @@ -9,7 +9,6 @@ import time # The following defines the HTML header used by all generated pages. -# html_header_1 = """\ @@ -53,28 +52,23 @@ html_header_3=""" API Reference # The HTML footer used by all generated pages. -# html_footer = """\ """ # The header and footer used for each section. -# section_title_header = "

" section_title_footer = "

" # The header and footer used for code segments. -# code_header = '
'
 code_footer = '
' # Paragraph header and footer. -# para_header = "

" para_footer = "

" # Block header and footer. -# block_header = '
' block_footer_start = """\
@@ -91,23 +85,19 @@ block_footer_end = """\ """ # Description header/footer. -# description_header = '
' description_footer = "

" # Marker header/inter/footer combination. -# marker_header = '
' marker_inter = "
" marker_footer = "
" # Source code extracts header/footer. -# source_header = '
\n'
 source_footer = "\n

" # Chapter header/inter/footer. -# chapter_header = '

' chapter_inter = '

  • ' chapter_footer = '
' @@ -124,7 +114,6 @@ index_footer_end = """\ # source language keyword coloration/styling -# keyword_prefix = '' keyword_suffix = '' @@ -134,38 +123,34 @@ section_synopsis_footer = '' # Translate a single line of source to HTML. This will convert # a "<" into "<.", ">" into ">.", etc. -# def html_quote( line ): - result = string.replace( line, "&", "&" ) + result = string.replace( line, "&", "&" ) result = string.replace( result, "<", "<" ) result = string.replace( result, ">", ">" ) return result # same as 'html_quote', but ignores left and right brackets -# def html_quote0( line ): return string.replace( line, "&", "&" ) def dump_html_code( lines, prefix = "" ): # clean the last empty lines - # l = len( self.lines ) while l > 0 and string.strip( self.lines[l - 1] ) == "": l = l - 1 # The code footer should be directly appended to the last code # line to avoid an additional blank line. - # print prefix + code_header, - for line in self.lines[0 : l+1]: + for line in self.lines[0 : l + 1]: print '\n' + prefix + html_quote( line ), print prefix + code_footer, -class HtmlFormatter( Formatter ): +class HtmlFormatter( Formatter ): def __init__( self, processor, project_title, file_prefix ): Formatter.__init__( self, processor ) @@ -207,7 +192,6 @@ class HtmlFormatter( Formatter ): def make_html_word( self, word ): """analyze a simple word to detect cross-references and styling""" # look for cross-references - # m = re_crossref.match( word ) if m: try: @@ -245,8 +229,8 @@ class HtmlFormatter( Formatter ): for word in words[1:]: line = line + " " + self.make_html_word( word ) # convert `...' quotations into real left and right single quotes - line = re.sub( r"(^|\W)`(.*?)'(\W|$)", - r'\1‘\2’\3', + line = re.sub( r"(^|\W)`(.*?)'(\W|$)", \ + r'\1‘\2’\3', \ line ) return para_header + line + para_footer @@ -275,7 +259,7 @@ class HtmlFormatter( Formatter ): def print_html_field( self, field ): if field.name: - print "

"+field.name+"

" + print "

" + field.name + "

" print self.make_html_items( field.items ) @@ -294,11 +278,9 @@ class HtmlFormatter( Formatter ): if name == block_name: # this is the current block name, if any result = result + prefix + '' + name + '' - elif re_source_keywords.match( name ): # this is a C keyword result = result + prefix + keyword_prefix + name + keyword_suffix - elif self.identifiers.has_key( name ): # this is a known identifier block = self.identifiers[name] @@ -318,7 +300,7 @@ class HtmlFormatter( Formatter ): print "" for field in fields: if len( field.name ) > 22: - print "" + print "" print "" for c in range( self.columns ): - i = r + c*rows + i = r + c * rows if i < count: bname = self.block_index[r + c * rows] url = self.index_items[bname] @@ -380,7 +361,7 @@ class HtmlFormatter( Formatter ): print "
"+field.name+"
" + field.name + "
" else: print "
" + field.name + "" @@ -336,7 +318,6 @@ class HtmlFormatter( Formatter ): # all of them as a single table # table_fields.append( field ) - else: if table_fields: self.print_html_field_list( table_fields ) @@ -368,7 +349,7 @@ class HtmlFormatter( Formatter ): for r in range( rows ): line = "
" - print index_footer_start + \ + print index_footer_start + \ self.file_prefix + "toc.html" + \ index_footer_end @@ -418,7 +399,9 @@ class HtmlFormatter( Formatter ): print chapter_footer def toc_index( self, index_filename ): - print chapter_header + 'Global Index' + chapter_inter + chapter_footer + print chapter_header + \ + 'Global Index' + \ + chapter_inter + chapter_footer def toc_exit( self ): print self.html_footer @@ -510,7 +493,7 @@ class HtmlFormatter( Formatter ): def block_exit( self, block ): print block_footer_start + self.file_prefix + "index.html" + \ - block_footer_middle + self.file_prefix + "toc.html" + \ + block_footer_middle + self.file_prefix + "toc.html" + \ block_footer_end def section_exit( self, section ): diff --git a/src/tools/docmaker/utils.py b/src/tools/docmaker/utils.py index adafa4fa5..1d96658c7 100644 --- a/src/tools/docmaker/utils.py +++ b/src/tools/docmaker/utils.py @@ -83,7 +83,7 @@ def check_output(): if output_dir: if output_dir != "": if not os.path.isdir( output_dir ): - sys.stderr.write( "argument" + " '" + output_dir + "' " + + sys.stderr.write( "argument" + " '" + output_dir + "' " + \ "is not a valid directory" ) sys.exit( 2 ) else: @@ -105,7 +105,6 @@ def file_exists( pathname ): def make_file_list( args = None ): """builds a list of input files from command-line arguments""" - file_list = [] # sys.stderr.write( repr( sys.argv[1 :] ) + '\n' )