| #!/usr/bin/env python |
| # |
| # DocMaker is a very simple program used to generate HTML documentation |
| # from the source files of the FreeType packages. |
| # |
| |
| import fileinput, sys, string |
| |
| # This function is used to parse a source file, and extract comment blocks |
| # from it. The following comment block formats are recognized : |
| # |
| # /************************** |
| # * |
| # * FORMAT1 |
| # * |
| # * |
| # * |
| # * |
| # *************************/ |
| # |
| # /**************************/ |
| # /* */ |
| # /* FORMAT2 */ |
| # /* */ |
| # /* */ |
| # /* */ |
| # /* */ |
| # |
| # /**************************/ |
| # /* */ |
| # /* FORMAT3 */ |
| # /* */ |
| # /* */ |
| # /* */ |
| # /* */ |
| # /**************************/ |
| # |
| # Each block is modeled as a simple list of text strings |
| # The function returns a list of blocks, i.e. a list of strings lists |
| # |
| |
| def make_block_list(): |
| """parse a file and extract comments blocks from it""" |
| |
| list = [] |
| block = [] |
| format = 0 |
| |
| for line in fileinput.input(): |
| |
| line = string.strip(line) |
| l = len(line) |
| |
| if format == 0: |
| if l > 3 and line[0:3] == '/**': |
| i = 3 |
| while (i < l) and (line[i] == '*'): |
| i = i+1 |
| |
| if i == l: |
| # this is '/**' followed by any number of '*', the |
| # beginning of a Format 1 block |
| # |
| block = []; |
| format = 1; |
| |
| elif (i == l-1) and (line[i] == '/'): |
| # this is '/**' followed by any number of '*', followed |
| # by a '/', i.e. the beginning of a Format 2 or 3 block |
| # |
| block = []; |
| format = 2; |
| |
| ############################################################## |
| # |
| # FORMAT 1 |
| # |
| elif format == 1: |
| |
| # if the line doesn't begin with a "*", something went |
| # wrong, and we must exit, and forget the current block.. |
| if (l == 0) or (line[0] != '*'): |
| block = [] |
| format = 0 |
| |
| # otherwise, we test for an end of block, which is an |
| # arbitrary number of '*', followed by '/' |
| else: |
| i = 1 |
| while (i < l) and (line[i] == '*'): |
| i = i+1 |
| |
| # test for the end of the block |
| if (i < l) and (line[i] == '/'): |
| if block != []: list.append( block ) |
| format = 0 |
| block = [] |
| |
| else: |
| block.append( line[1:] ) |
| |
| ############################################################## |
| # |
| # FORMAT 2 |
| # |
| elif format == 2: |
| |
| # if the line doesn't begin with '/*' and end with '*/', |
| # this is the end of the format 2 format.. |
| if (l < 4 ) or (line[:2] != '/*') or (line[-2:] != '*/'): |
| if block != []: list.append(block) |
| block = [] |
| format = 0 |
| continue |
| |
| # remove the start and end comment delimiters, then right-strip |
| # the line |
| line = string.rstrip(line[2:-2]) |
| |
| # check for end of a format2 block, i.e. a run of '*' |
| if string.count(line,'*') == l-4: |
| if block != []: list.append(block) |
| block = [] |
| format = 0 |
| else: |
| # otherwise, add the line to the current block |
| block.append(line) |
| |
| return list |
| |
| |
| # This function is only used for debugging |
| # |
| def dump_block_list( list ): |
| """dump a comment block list""" |
| for block in list: |
| print "----------------------------------------" |
| for line in block: |
| print line |
| print "---------the end-----------------------" |
| |
| |
| |
| |
| |
| ###################################################################################### |
| # |
| # |
| # The DocParagraph is used to store either simple text paragraph or |
| # source code lines |
| # |
| # |
| # If the paragraph contains source code (use code=1 when initializing the |
| # object), self.lines is a list of source code strings |
| # |
| # Otherwise, self.lines is simply a list of words for the paragraph |
| # |
| class DocParagraph: |
| |
| def __init__(self,code=0,margin=0): |
| self.lines = [] |
| self.code = code |
| self.margin = margin |
| |
| def add(self,line): |
| |
| if self.code==0: |
| # get rid of unwanted spaces in the paragraph |
| self.lines.extend( string.split(line) ) |
| |
| else: |
| # remove margin whitespace |
| if string.strip( line[:self.margin] ) == "": line = line[self.margin:] |
| self.lines.append(line) |
| |
| |
| def dump(self): |
| |
| max_width = 50 |
| |
| if self.code == 0: |
| cursor = 0 |
| line = "" |
| |
| for word in self.lines: |
| |
| if cursor+len(word)+1 > max_width: |
| print line |
| cursor = 0 |
| line = "" |
| |
| line = line + word + " " |
| cursor = cursor + len(word) + 1 |
| |
| if cursor > 0: |
| print line |
| |
| else: |
| for line in self.lines: |
| print "--" + line |
| |
| print "" |
| |
| |
| ###################################################################################### |
| # |
| # |
| # The DocContent class is used to store the content of a given marker |
| # Each DocContent can have its own text, plus a list of fields. Each field |
| # has its own text too |
| # |
| # Hence, the following lines : |
| # |
| # """ |
| # Some arbitraty text: |
| # |
| # fieldone :: some arbitraty text for this field, |
| # note that the text stretches to several lines |
| # |
| # fieldtwo :: some other text |
| # |
| # """ |
| # |
| # will be stored as (each text is a list of string: |
| # |
| # self.fields = [ "", "fieldone", "fieldtwo" ] |
| # self.texts = [ |
| # [ "some arbitraty text for this field," , |
| # "note that the text stretches to several lines" ], |
| # |
| # [ "some other text" ] |
| # ] |
| # |
| # |
| class DocContent: |
| |
| def __init__(self, paragraph_lines=[]): |
| |
| self.fields = [] |
| self.texts = [] |
| |
| code_mode = 0 |
| code_margin = 0 |
| |
| field = "" |
| text = [] |
| paragraph = None |
| |
| for aline in paragraph_lines: |
| |
| if code_mode == 0: |
| line = string.lstrip(aline) |
| l = len(line) |
| margin = len(aline) - l |
| |
| # if the line is empty, this is the end of the current |
| # paragraph |
| if line == "": |
| if paragraph: |
| text.append(paragraph) |
| paragraph = None |
| continue |
| |
| # test for the beginning of a code block, i.e.'{' is the first |
| # and only character on the line.. |
| # |
| if line == '{': |
| code_mode = 1 |
| code_margin = margin |
| if paragraph: |
| text.append(paragraph) |
| paragraph = DocParagraph( 1, margin ) |
| continue |
| |
| words = string.split(line) |
| |
| # test for a field delimiter on the start of the line, i.e. |
| # the oken `::' |
| # |
| if len(words) >= 2 and words[1] == "::": |
| if paragraph: |
| text.append(paragraph) |
| paragraph = None |
| |
| self.fields.append(field) |
| self.texts.append(text) |
| |
| field = words[0] |
| text = [] |
| words = words[2:] |
| |
| if len(words) > 0: |
| line = string.join(words) |
| if not paragraph: |
| paragraph = DocParagraph() |
| paragraph.add( line ) |
| |
| else: |
| line = aline |
| |
| # the code block ends with a line that has a single '}' on it |
| if line == " "*code_margin+'}': |
| text.append(paragraph) |
| paragraph = None |
| code_mode = 0 |
| code_margin = 0 |
| |
| # otherwise, add the line to the current paragraph |
| else: |
| paragraph.add(line) |
| |
| if paragraph: |
| text.append(paragraph) |
| |
| self.fields.append( field ) |
| self.texts.append( text ) |
| |
| |
| |
| def dump(self): |
| for i in range(len(self.fields)): |
| field = self.fields[i] |
| if field: print "<field "+field+">" |
| |
| for paras in self.texts[i]: |
| paras.dump() |
| |
| if field: print "</field> " |
| |
| |
| ###################################################################################### |
| # |
| # |
| # The DocBlock class is used to store a given comment block. It contains |
| # a list of markers, as well as a list of contents for each marker. |
| # |
| # |
| class DocBlock: |
| |
| def __init__(self, block_line_list=[]): |
| self.markers = [] |
| self.contents = [] |
| |
| marker = "" |
| content = [] |
| alphanum = string.letters + string.digits + "_" |
| |
| for line in block_line_list: |
| line2 = string.lstrip(line) |
| l = len(line2) |
| margin = len(line) - l |
| |
| if l > 3 and line2[0] == '<': |
| i = 1 |
| while i < l and line2[i] in alphanum: i = i+1 |
| if i < l and line2[i] == '>': |
| if marker or content: |
| self.add( marker, content ) |
| marker = line2[1:i] |
| content = [] |
| line2 = string.lstrip(line2[i+1:]) |
| l = len(line2) |
| line = " "*margin + line2 |
| |
| content.append(line) |
| |
| if marker or content: |
| self.add( marker, content ) |
| |
| |
| def add( self, marker, lines ): |
| |
| # remove the first and last empty lines from the content list |
| l = len(lines) |
| if l > 0: |
| i = 0 |
| while l > 0 and string.strip(lines[l-1]) == "": l = l-1 |
| while i < l and string.strip(lines[i]) == "": i = i+1 |
| lines = lines[i:l] |
| l = len(lines) |
| |
| # add a new marker only if its marker and its content list aren't empty |
| if l > 0 and marker: |
| self.markers.append(marker) |
| self.contents.append(lines) |
| |
| def dump( self ): |
| for i in range( len(self.markers) ): |
| print "["+self.markers[i]+"]" |
| for line in self.contents[i]: |
| print "-- "+line |
| |
| def doc_contents(self): |
| contents = [] |
| for item in self.contents: |
| contents.append( DocContent(item) ) |
| return contents |
| |
| |
| def dump_doc_blocks( block_list ): |
| for block in block_list: |
| docblock = DocBlock(block) |
| docblock.dump() |
| print "<<------------------->>" |
| |
| |
| # |
| # |
| # |
| def dump_single_content( block_list ): |
| |
| block = block_list[0] |
| docblock = DocBlock(block) |
| |
| print "<block>" |
| for i in range(len(docblock.markers)): |
| marker = docblock.markers[i] |
| contents = docblock.contents[i] |
| |
| print "<marker "+marker+">" |
| doccontent = DocContent( contents ) |
| |
| doccontent.dump() |
| |
| print "</marker>" |
| |
| print "</block>" |
| |
| def dump_doc_contents( block_list ): |
| |
| for block in block_list: |
| docblock = DocBlock(block) |
| print "<block>" |
| |
| for i in range(len(docblock.markers)): |
| print "<marker "+docblock.markers[i]+">" |
| content = DocContent( docblock.contents[i] ) |
| content.dump() |
| print "</marker>" |
| print "</block>" |
| |
| def main(argv): |
| """main program loop""" |
| print "extracting comment blocks from sources .." |
| list = make_block_list() |
| |
| # dump_block_list( list ) |
| |
| # dump_doc_blocks( list ) |
| |
| # print "dumping block contents .." |
| dump_doc_contents(list) |
| |
| # dump_single_content(list) |
| |
| # If called from the command line |
| if __name__=='__main__': main(sys.argv) |