minhngoc25a
/
freetype2
mirror of git://git.savannah.gnu.org/freetype/freetype2.git
2
1
Fork 2
Code Issues 9 Releases Wiki Activity

updates to the API reference generators 

the basic parsing routines seem to work ok
we now generate a list of DocBlock objects from
a list of input file, we now need to sort them
by "kind" (i.e. type/macro/functions) to generate
several web pages, as well as a global index
This commit is contained in:
David Turner 2000-10-26 07:52:40 +00:00
parent ab88a56eed
commit f81ce2c4c5
1 changed files with 510 additions and 430 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

940
docs/docmaker.py
View File

@ -28,12 +28,9 @@ html_header = """
vlink="#51188E"
alink="#FF0000">
<center><h1>FreeType 2 API Reference</h1></center>
<center><table width="80%"><tr><td>
"""
html_footer = """
</td></tr>
</table></center>
</body>
</html>
"""
@ -49,12 +46,12 @@ code_footer = """
para_header = "<p>"
para_footer = "</p>"
block_header = """<table width="100%"><tr><td>"""
block_footer = "</table>"
block_header = """<center><hr width="550"><table width="550"><tr><td>"""
block_footer = "</table></center>"
source_header = """<table width="100%"><tr bgcolor="#D6E8FF" width="100%"><td><pre>
source_header = """<center><table width="550"><tr bgcolor="#D6E8FF" width="100%"><td><pre>
"""
source_footer = """</pre></table>
source_footer = """</pre></table></center>
<br><br>
"""
@ -144,6 +141,501 @@ source_footer = """</pre></table>
#
##############################################################################
#
# The DocCode class is used to store source code lines
#
# self.lines contains a set of source code lines that will
# be dumped as HTML in a <PRE> tag.
#
# 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:
def __init__( self, margin = 0 ):
self.lines = []
self.margin = margin
def add( self, line ):
# remove margin whitespace
if string.strip( line[: self.margin] ) == "":
line = line[self.margin :]
self.lines.append( line )
def dump( self ):
for line in self.lines:
print "--" + line
print ""
def get_identifier( self ):
# this function should never be called
return "UNKNOWN_CODE_IDENTIFIER!!"
def dump_html( self ):
# clean the last empty lines
l = len( self.lines ) - 1
while l > 0 and string.strip( self.lines[l - 1] ) == "":
l = l - 1
print code_header
for line in self.lines[0 : l]:
print line
print code_footer
##############################################################################
#
# The DocParagraph is used to store text paragraphs
# self.words is simply a list of words for the paragraph
#
# the paragraph is filled line by line by the parser..
#
class DocParagraph:
def __init__( self ):
self.words = []
def add( self, line ):
# get rid of unwanted spaces in the paragraph
#
# the following line is the same as
#
# self.words.extend( string.split( line ) )
#
# but older Python versions don't have the `extend' attribute
#
last = len(self.words)
self.words[last:last] = string.split( line )
# this function is used to retrieve the first word of a given
# paragraph..
def get_identifier( self ):
if self.words:
return self.words[0]
# should never happen
return "UNKNOWN_PARA_IDENTIFIER!!"
def dump( self ):
max_width = 50
cursor = 0
line = ""
for word in self.words:
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
#print "§" #for debugging only
def dump_html( self ):
print para_header
self.dump()
print para_footer
###########################################################################
#
# DocContent is used to store the content of a given marker.
#
# the "self.items" list contains (field,elements) record, where
# "field" corresponds to a given structure fields or function
# parameter (indicated by a "::"), or NULL for a normal section
# of text/code
#
# hence, the following example:
#
# <MyMarker>
# this is an example of what can be put in a content section,
#
# a second line of example text
#
# x :: a simple test field, with some content
# y :: even before, this field has some code content
# {
# y = x+2;
# }
#
# should be stored as
# [ ( None, [ DocParagraph, DocParagraph] ),
# ( "x", [ DocParagraph ] ),
# ( "y", [ DocParagraph, DocCode ] ) ]
#
# in self.items
#
# the DocContent object is entirely built at creation time, you must
# pass a list of input text lines lin the "lines_list" parameter..
#
#
class DocContent:
def __init__( self, lines_list ):
self.items = []
code_mode = 0
code_margin = 0
text = []
paragraph = None # represents the current DocParagraph
code = None # represents the current DocCode
elements = [] # the list of elements for the current field,
# contains DocParagraph or DocCode objects
field = None # the current field
for aline in lines_list:
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 l == 0 or line == '{':
if paragraph:
elements.append( paragraph )
paragraph = None
if line == "":
continue
code_mode = 1
code_margin = margin
code = None
continue
words = string.split( line )
# test for a field delimiter on the start of the line, i.e.
# the token `::'
#
if len( words ) >= 2 and words[1] == "::":
# start a new field - complete current paragraph if any
if paragraph:
elements.append( paragraph )
paragraph = None
# append previous "field" to self.items
self.items.append( ( field, elements ) )
# start new field and elements list
field = words[0]
elements = []
words = words[2 :]
# append remaining words to current paragraph
if len( words ) > 0:
line = string.join( words )
if not paragraph:
paragraph = DocParagraph()
paragraph.add( line )
else:
# we're in code mode..
line = aline
# the code block ends with a line that has a single '}' on it
# that is located at the same column that the opening
# accolade..
if line == " " * code_margin + '}':
if code:
elements.append( code )
code = None
code_mode = 0
code_margin = 0
# otherwise, add the line to the current paragraph
else:
if not code:
code = DocCode()
code.add( line )
if paragraph:
elements.append( paragraph )
if code:
elements.append( code )
self.items.append( ( field, elements ) )
def get_identifier( self ):
if self.items:
item = self.items[0]
for element in item[1]:
return element.get_identifier()
# should never happen
return "UNKNOWN_CONTENT_IDENTIFIER!!"
def dump( self ):
for item in self.items:
field = item[0]
if field:
print "<field " + field + ">"
for element in item[1]:
element.dump()
if field:
print "</field> "
def dump_html( self ):
n = len( self.items )
in_table = 0
for i in range( n ):
item = self.items[i]
field = item[0]
if not field:
if in_table:
print "</td></tr></table>"
in_table = 0
for element in item[1]:
element.dump_html()
else:
if not in_table:
print "<table cellpadding=4><tr valign=top><td>"
in_table = 1
else:
print "</td></tr><tr valign=top><td>"
print "<b>" + field + "</b></td><td>"
for element in item[1]:
element.dump_html()
if in_table:
print "</td></tr></table>"
######################################################################################
#
#
# 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.
#
# "self.items" is a list of ( marker, contents ) elements, where
# 'marker' is a lowercase marker string, and 'contents' is a DocContent
# object
#
# "self.source" is simply a list of text lines taken from the
# uncommented source itself..
#
# finally, "self.identifier" is a simple identifier used to
# uniquely identify the block
#
class DocBlock:
def __init__( self, block_line_list = [], source_line_list = [] ):
self.items = [] # current ( marker, contents ) list
self.identifier = None
marker = None # current marker
content = [] # current content lines list
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:
ender = None
if line2[0] == '<':
ender = '>'
elif line2[0] == '@':
ender = ':'
if ender:
i = 1
while i < l and line2[i] in alphanum:
i = i + 1
if i < l and line2[i] == ender:
if marker and 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 and content:
self.add( marker, content )
self.source = []
if self.items:
self.source = source_line_list
# this function is used to add a new element to self.items
# 'marker' is a marker string, or None
# 'lines' is a list of text lines used to compute a list of
# DocContent objects
#
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:
content = DocContent(lines)
self.items.append( ( string.lower(marker), content ) )
if not self.identifier:
self.identifier = content.get_identifier()
def dump( self ):
for i in range( len( self.items ) ):
print "[" + self.items[i][0] + "]"
content = self.items[i][1]
content.dump()
def dump_html( self ):
types = [ 'type', 'struct', 'functype', 'function', 'constant',
'enum', 'macro' ]
if not self.items:
return
# start of a block
print block_header
print "<h2>" + self.identifier + "</h2>"
# print source code
if not self.source:
return
lines = self.source
l = len( lines ) - 1
while l >= 0 and string.strip( lines[l] ) == "":
l = l - 1
print source_header
for line in lines[0 : l + 1]:
print line
print source_footer
# dump each (marker,content) element
for element in self.items:
marker = element[0]
content = element[1]
if marker == "description":
print "<ul>"
content.dump_html()
print "</ul>"
elif not (marker in types):
print "<h4>" + marker + "</h4>"
print "<ul>"
content.dump_html()
print "</ul>"
print ""
print block_footer
# filter a given list of DocBlocks. Returns a new list
# of DocBlock objects that only contains element whose
# "type" (i.e. first marker) is in the "types" parameter
#
def filter_blocks( block_list, types ):
new_list = []
for block in block_list:
if block.items:
element = block.items[0]
marker = element[0]
if marker in types:
new_list.append( block )
return new_list
# perform a lexicographical comparison of two DocBlock
# objects. Returns -1, 0 or 1
#
def block_lexicographical_compare( b1, b2 ):
if not b1.identifier:
return -1
if not b2.identifier:
return 1
id1 = string.lower(b1.identifier)
id2 = string.lower(b2.identifier)
if id1 < id2:
return -1
elif id1 == id2:
return 0
else:
return 1
def block_make_list( source_block_list ):
list = []
for block in source_block_list:
docblock = DocBlock( block[0], block[1] )
list.append( docblock )
return list
# dump a list block as a single HTML page
#
def dump_html_1( block_list ):
print html_header
for block in block_list:
block.dump_html()
print html_footer
def make_block_list():
"""parse a file and extract comments blocks from it"""
@ -174,7 +666,7 @@ def make_block_list():
# stripped version of the line
line2 = string.strip( line )
l = len( line2 )
# if this line begins with a comment and we are processing some
# source, exit to state 0
#
@ -242,7 +734,7 @@ def make_block_list():
format = 0
else:
# otherwise simply append line to current block
block.append( line2 )
block.append( line2[i:] )
continue
@ -309,432 +801,20 @@ def dump_block_list( list ):
##############################################################################
#
# The DocCode class is used to store source code lines
#
class DocCode:
def __init__( self, margin = 0 ):
self.lines = []
self.margin = margin
def add( self, line ):
# remove margin whitespace
if string.strip( line[: self.margin] ) == "":
line = line[self.margin :]
self.lines.append( line )
def dump( self ):
max_width = 50
for line in self.lines:
print "--" + line
print ""
def dump_html( self ):
# clean the last empty lines
l = len( self.lines ) - 1
while len > 0 and string.strip( lines[len - 1] ) == "":
len = len - 1
print code_header
for line in self.lines[0 : len]:
print lines
print code_footer
##############################################################################
#
# The DocParagraph is used to store text paragraphs
# self.words is simply a list of words for the paragraph
#
class DocParagraph:
def __init__( self ):
self.words = []
def add( self, line ):
# get rid of unwanted spaces in the paragraph
#
# the following line is the same as
#
# self.words.extend( string.split( line ) )
#
# but older Python versions don't have the `extend' attribute
#
last = len(self.words)
self.words[last:last] = string.split( line )
def dump( self ):
max_width = 50
cursor = 0
line = ""
for word in self.words:
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
print ""
def dump_html( self ):
print para_header
self.dump()
print para_footer
###########################################################################
#
# DocContent is used to store the content of a given marker.
#
# the "self.items" list contains (field,elements) record, where
# "field" corresponds to a given structure fields or function
# parameter (indicated by a "::"), or NULL for a normal section
# of text/code
#
# hence, the following example:
#
# <MyMarker>
# this is an example of what can be put in a content section,
#
# a second line of example text
#
# x :: a simple test field, with some content
# y :: even before, this field has some code content
# {
# y = x+2;
# }
#
# should be stored as
# [ ( None, [ DocParagraph, DocParagraph] ),
# ( "x", [ DocParagraph ] ),
# ( "y", [ DocParagraph, DocCode ] ) ]
#
#
class DocContent:
def __init__( self, lines_list ):
self.items = []
code_mode = 0
code_margin = 0
text = []
paragraph = None
code = None
elements = []
field = None
for aline in lines_list:
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 l == 0 or line == '{':
if paragraph:
elements.append( paragraph )
paragraph = None
if line == "":
continue
code_mode = 1
code_margin = margin
code = None
continue
words = string.split( line )
# test for a field delimiter on the start of the line, i.e.
# the token `::'
#
if len( words ) >= 2 and words[1] == "::":
if paragraph:
elements.append( paragraph )
paragraph = None
self.items.append( ( field, elements ) )
field = words[0]
elements = []
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 + '}':
if code:
elements.append( code )
code = None
code_mode = 0
code_margin = 0
# otherwise, add the line to the current paragraph
else:
if not code:
code = DocCode()
code.add( line )
if paragraph:
elements.append( paragraph )
if code:
elements.append( code )
self.items.append( ( field, elements ) )
def dump( self ):
for item in self.items:
field = item[0]
if field:
print "<field " + field + ">"
for element in item[1]:
element.dump()
if field:
print "</field> "
def dump_html( self ):
n = len( self.items )
in_table = 0
for i in range( n ):
item = self.items[i]
field = item[0]
if not field:
if in_table:
print "</td></tr></table>"
in_table = 0
for element in item[1]:
element.dump_html()
else:
if not in_table:
print "<table cellpadding=4><tr valign=top><td>"
in_table = 1
else:
print "</td></tr><tr valign=top><td>"
print "<b>" + field + "</b></td><td>"
for element in item[1]:
element.dump_html()
if in_table:
print "</td></tr></table>"
######################################################################################
#
#
# 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 = [], source_line_list = [] ):
self.markers = []
self.contents = []
self.source = source_line_list
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 dump_html_1( block_list ):
print html_header
types = [ 'Type', 'Struct', 'FuncType', 'Function', 'Constant',
'Enumeration' ]
for block in block_list:
docblock = DocBlock( block[0], block[1] )
if len( docblock.markers ) == 0:
continue
print block_header
for i in range( len( docblock.markers ) ):
marker = docblock.markers[i]
content = docblock.contents[i]
dcontent = DocContent( content )
if marker == "Description":
print "<ul><p>"
dcontent.dump()
print "</p></ul>"
elif marker in types:
print "<h3><font color=blue>" + content[0] + "</font></h3>"
else:
print "<h4>" + marker + "</h4>"
print "<ul><p>"
dcontent.dump_html()
print "</p></ul>"
print ""
print block_footer
# print source code
lines = block[1]
l = len( lines ) - 1
while l >= 0 and string.strip( lines[l] ) == "":
l = l - 1
print source_header
for line in lines[0 : l + 1]:
print line
print source_footer
print html_footer
def main( argv ):
"""main program loop"""
sys.stderr.write( "extracting comment blocks from sources...\n" )
list = make_block_list()
list = block_make_list(list)
dump_html_1( list )
list2 = filter_blocks( list, ['type','macro','enum','constant', 'functype'] )
#list2 = list
list2.sort( block_lexicographical_compare )
dump_html_1( list2 )
#dump_doc_blocks( list )
#dump_block_lists( list )
#dump_html_1( list )
# If called from the command line