added the DocMaker python script that will be used to generate the HTML documentation from the C source files
This commit is contained in:
David Turner
parent
0db8d1ab84
commit
ecbfb5fa9a
|
|
@ -0,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)
|
||||
Loading…
Reference in New Issue