From ee42805e5f49ffc6c46d9f1045ca2fc63a09f246 Mon Sep 17 00:00:00 2001 From: David Turner Date: Fri, 16 Jan 2004 14:26:32 +0000 Subject: [PATCH] * src/tools/docmaker/*: updating the DocMaker tool, adding a new tool named "docbeauty" to beautify the documentation comments (e.g. convert them to a single block border mode) --- src/tools/docmaker/docbeauty.py | 100 ++++++++++++++++++++++++++++++++ src/tools/docmaker/docmaker.py | 42 -------------- src/tools/docmaker/formatter.py | 9 +++ src/tools/docmaker/sources.py | 6 +- src/tools/docmaker/utils.py | 43 +++++++++++++- 5 files changed, 154 insertions(+), 46 deletions(-) create mode 100644 src/tools/docmaker/docbeauty.py diff --git a/src/tools/docmaker/docbeauty.py b/src/tools/docmaker/docbeauty.py new file mode 100644 index 000000000..057ed2464 --- /dev/null +++ b/src/tools/docmaker/docbeauty.py @@ -0,0 +1,100 @@ +#!/usr/bin/env python +# +# DocBeuaty 0.2 (c) 2003 David Turner +# +# This program is used to beautify the documentation comments used +# in the FreeType 2 public headers. +# +# For now, it basically converts all document blocks to a single +# format. It should be able to re-justify all text later in the +# future.. +# + +from sources import * +from utils import * + +import utils + +import sys, os, time, string, getopt + + +def beautify_block( block ): + if block.content: + # only beautify documentation blocks + lines = [ " /*************************************************************************" ] + for l in block.content: + lines.append( " *" + l ) + lines.append( " */" ) + + block.lines = lines + + +def usage(): + print "\nDocBeauty 0.1 Usage information\n" + print " docbeauty [options] file1 [ file2 ... ]\n" + print "using the following options:\n" + print " -h : print this page" + print " -b : backup original files with the 'orig' extension" + print "" + print " --backup : same as -b" + + +def main( argv ): + """main program loop""" + + global output_dir + + try: + opts, args = getopt.getopt( sys.argv[1:], + "hb", + [ "help", "backup" ] ) + + except getopt.GetoptError: + usage() + sys.exit( 2 ) + + if args == []: + usage() + sys.exit( 1 ) + + # process options + # + output_dir = None + do_backup = None + + for opt in opts: + if opt[0] in ( "-h", "--help" ): + usage() + sys.exit( 0 ) + + if opt[0] in ( "-b", "--backup" ): + do_backup = 1 + + # create context and processor + source_processor = SourceProcessor() + + # retrieve the list of files to process + 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: + for line in block.lines: + file.write( line ) + file.write( "\n" ) + file.close() + except: + ok = 0 + +# if called from the command line +# +if __name__ == '__main__': + main( sys.argv ) + + +# eof diff --git a/src/tools/docmaker/docmaker.py b/src/tools/docmaker/docmaker.py index 285bcd6a2..eea5f4f49 100644 --- a/src/tools/docmaker/docmaker.py +++ b/src/tools/docmaker/docmaker.py @@ -24,48 +24,6 @@ import utils import sys, os, time, string, glob, getopt -def file_exists( pathname ): - """checks that a given file exists""" - result = 1 - try: - file = open( pathname, "r" ) - file.close() - except: - result = None - sys.stderr.write( pathname + " couldn't be accessed\n" ) - - return result - - -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' ) - - if not args: - args = sys.argv[1 :] - - for pathname in args: - if string.find( pathname, '*' ) >= 0: - newpath = glob.glob( pathname ) - newpath.sort() # sort files -- this is important because - # of the order of files - else: - newpath = [pathname] - - file_list.extend( newpath ) - - if len( file_list ) == 0: - file_list = None - else: - # now filter the file list to remove non-existing ones - file_list = filter( file_exists, file_list ) - - return file_list - - - def usage(): print "\nDocMaker 0.2 Usage information\n" print " docmaker [options] file1 [ file2 ... ]\n" diff --git a/src/tools/docmaker/formatter.py b/src/tools/docmaker/formatter.py index 36d72aeca..0cabca7a8 100644 --- a/src/tools/docmaker/formatter.py +++ b/src/tools/docmaker/formatter.py @@ -1,6 +1,15 @@ from sources import * from content import * from utils import * + +# This is the base Formatter class. its purpose is to convert +# a content processor's data into specific documents (i.e. table of +# contents, global index, and individual API reference indices). +# +# You'll need to sub-class it to output anything sensible. For example, +# the file tohtml.py contains the definition of the HtmlFormatter sub-class +# used to output, you guessed it, HTML ! +# class Formatter: diff --git a/src/tools/docmaker/sources.py b/src/tools/docmaker/sources.py index c270e5411..0a2942b98 100644 --- a/src/tools/docmaker/sources.py +++ b/src/tools/docmaker/sources.py @@ -200,7 +200,7 @@ class SourceBlock: self.processor = processor self.filename = filename self.lineno = lineno - self.lines = lines + self.lines = lines[:] self.format = processor.format self.content = [] @@ -328,9 +328,9 @@ class SourceProcessor: """process a normal line and check if it's the start of a new block""" for f in re_source_block_formats: if f.start.match( line ): - self.add_block_lines() + self.add_block_lines() self.format = f - self.lineno = fileinput.filelineno() + self.lineno = fileinput.filelineno() self.lines.append( line ) diff --git a/src/tools/docmaker/utils.py b/src/tools/docmaker/utils.py index 6d4653db5..16d51caac 100644 --- a/src/tools/docmaker/utils.py +++ b/src/tools/docmaker/utils.py @@ -1,4 +1,4 @@ -import string, sys, os +import string, sys, os, glob # current output directory # @@ -85,3 +85,44 @@ def check_output( ): sys.exit( 2 ) else: output_dir = None + +def file_exists( pathname ): + """checks that a given file exists""" + result = 1 + try: + file = open( pathname, "r" ) + file.close() + except: + result = None + sys.stderr.write( pathname + " couldn't be accessed\n" ) + + return result + + +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' ) + + if not args: + args = sys.argv[1 :] + + for pathname in args: + if string.find( pathname, '*' ) >= 0: + newpath = glob.glob( pathname ) + newpath.sort() # sort files -- this is important because + # of the order of files + else: + newpath = [pathname] + + file_list.extend( newpath ) + + if len( file_list ) == 0: + file_list = None + else: + # now filter the file list to remove non-existing ones + file_list = filter( file_exists, file_list ) + + return file_list +