ref: ecbfb5fa9a8f2a9a4649eaead8e0092d60512a49
parent: 0db8d1ab84d3bbde5d1c77e8e932120bee3f1a06
author: David Turner <[email protected]>
date: Mon Jan 10 10:49:01 EST 2000
added the DocMaker python script that will be used to generate the HTML documentation from the C source files
--- /dev/null
+++ b/docs/docmaker.py
@@ -1,0 +1,457 @@
+#!/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)