2000-01-10 18:49:01 +03:00
|
|
|
|
#!/usr/bin/env python
|
|
|
|
|
#
|
|
|
|
|
# DocMaker is a very simple program used to generate HTML documentation
|
|
|
|
|
# from the source files of the FreeType packages.
|
|
|
|
|
#
|
2000-10-26 04:06:35 +04:00
|
|
|
|
# I should really be using regular expressions to do this, but hey,
|
|
|
|
|
# i'm too lazy right now, and the damn thing seems to work :-)
|
|
|
|
|
# - David
|
|
|
|
|
#
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
|
|
|
|
import fileinput, sys, string
|
|
|
|
|
|
2000-08-22 03:01:32 +04:00
|
|
|
|
html_header = """
|
|
|
|
|
<html>
|
|
|
|
|
<header>
|
|
|
|
|
<title>FreeType 2 API Reference</title>
|
|
|
|
|
<basefont face="Georgia, Arial, Helvetica, Geneva">
|
|
|
|
|
<style content="text/css">
|
|
|
|
|
P { text-align=justify }
|
|
|
|
|
H1 { text-align=center }
|
|
|
|
|
H2 { text-align=center }
|
|
|
|
|
LI { text-align=justify }
|
|
|
|
|
</style>
|
|
|
|
|
</header>
|
|
|
|
|
<body text="#000000"
|
|
|
|
|
bgcolor="#FFFFFF"
|
|
|
|
|
link="#0000EF"
|
|
|
|
|
vlink="#51188E"
|
|
|
|
|
alink="#FF0000">
|
|
|
|
|
<center><h1>FreeType 2 API Reference</h1></center>
|
|
|
|
|
"""
|
|
|
|
|
|
|
|
|
|
html_footer = """
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
|
|
|
|
"""
|
|
|
|
|
|
|
|
|
|
code_header = """
|
|
|
|
|
<font color=blue><pre>
|
|
|
|
|
"""
|
|
|
|
|
|
|
|
|
|
code_footer = """
|
|
|
|
|
</pre></font>
|
|
|
|
|
"""
|
|
|
|
|
|
|
|
|
|
para_header = "<p>"
|
|
|
|
|
para_footer = "</p>"
|
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
block_header = """<center><hr width="550"><table width="550"><tr><td>"""
|
|
|
|
|
block_footer = "</table></center>"
|
2000-08-22 03:01:32 +04:00
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
source_header = """<center><table width="550"><tr bgcolor="#D6E8FF" width="100%"><td><pre>
|
2000-08-22 03:01:32 +04:00
|
|
|
|
"""
|
2000-10-26 11:52:40 +04:00
|
|
|
|
source_footer = """</pre></table></center>
|
2000-08-22 03:01:32 +04:00
|
|
|
|
<br><br>
|
|
|
|
|
"""
|
|
|
|
|
|
|
|
|
|
# The FreeType 2 reference is extracted from the source files. These contain
|
|
|
|
|
# various comment blocks that follow one of the following formats:
|
2000-01-10 18:49:01 +03:00
|
|
|
|
#
|
|
|
|
|
# /**************************
|
|
|
|
|
# *
|
|
|
|
|
# * FORMAT1
|
|
|
|
|
# *
|
|
|
|
|
# *
|
|
|
|
|
# *
|
|
|
|
|
# *
|
|
|
|
|
# *************************/
|
|
|
|
|
#
|
|
|
|
|
# /**************************/
|
|
|
|
|
# /* */
|
|
|
|
|
# /* FORMAT2 */
|
|
|
|
|
# /* */
|
|
|
|
|
# /* */
|
|
|
|
|
# /* */
|
|
|
|
|
# /* */
|
|
|
|
|
#
|
|
|
|
|
# /**************************/
|
|
|
|
|
# /* */
|
|
|
|
|
# /* FORMAT3 */
|
|
|
|
|
# /* */
|
|
|
|
|
# /* */
|
|
|
|
|
# /* */
|
|
|
|
|
# /* */
|
|
|
|
|
# /**************************/
|
|
|
|
|
#
|
2000-08-22 03:01:32 +04:00
|
|
|
|
# Each block contains a list of markers, each one can be followed by
|
|
|
|
|
# some arbitrary text or a list of fields. Here's an example:
|
|
|
|
|
#
|
|
|
|
|
# <Struct>
|
|
|
|
|
# MyStruct
|
|
|
|
|
#
|
|
|
|
|
# <Description>
|
|
|
|
|
# this structure holds some data
|
|
|
|
|
#
|
|
|
|
|
# <Fields>
|
|
|
|
|
# x :: horizontal coordinate
|
|
|
|
|
# y :: vertical coordinate
|
|
|
|
|
#
|
|
|
|
|
#
|
|
|
|
|
# This example defines three markers: 'Struct', 'Description' & 'Fields'
|
|
|
|
|
# The first two markers contain arbitrary text, while the last one contains
|
|
|
|
|
# a list of field
|
|
|
|
|
#
|
|
|
|
|
# each field is simple of the format: WORD :: TEXT....
|
|
|
|
|
#
|
|
|
|
|
# Note that typically, each comment block is followed by some source
|
|
|
|
|
# code declaration that may need to be kept in the reference..
|
2000-01-10 18:49:01 +03:00
|
|
|
|
#
|
2000-10-23 22:32:55 +04:00
|
|
|
|
# Note that markers can alternatively be written as "@MARKER:"
|
|
|
|
|
# instead of "<MAKRER>". All marker identifiers are converted to
|
|
|
|
|
# lower case during parsing, in order to simply sorting..
|
|
|
|
|
#
|
2000-10-26 04:06:35 +04:00
|
|
|
|
# We associate with each block the following source lines that do not
|
|
|
|
|
# begin with a comment. For example, the following:
|
|
|
|
|
#
|
|
|
|
|
# /**********************************
|
|
|
|
|
# *
|
|
|
|
|
# * <mytag> blabla
|
|
|
|
|
# *
|
|
|
|
|
# */
|
|
|
|
|
#
|
|
|
|
|
# bla_bla_bla
|
|
|
|
|
# bilip_bilip
|
|
|
|
|
#
|
|
|
|
|
# /* - this comment acts as a separator - */
|
|
|
|
|
#
|
|
|
|
|
# blo_blo_blo
|
|
|
|
|
#
|
|
|
|
|
#
|
|
|
|
|
# will only keep the first two lines of sources with
|
|
|
|
|
# the "blabla" block
|
|
|
|
|
#
|
|
|
|
|
# However, the comment will be kept, with following source lines
|
|
|
|
|
# if it contains a starting '#' or '@' as in:
|
|
|
|
|
#
|
|
|
|
|
# /*@.....*/
|
|
|
|
|
# /*#.....*/
|
|
|
|
|
# /* @.....*/
|
|
|
|
|
# /* #.....*/
|
|
|
|
|
#
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
2000-08-22 03:01:32 +04:00
|
|
|
|
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
2000-08-22 03:01:32 +04:00
|
|
|
|
##############################################################################
|
2000-01-10 18:49:01 +03:00
|
|
|
|
#
|
2000-08-22 03:01:32 +04:00
|
|
|
|
# The DocCode class is used to store source code lines
|
2000-01-10 18:49:01 +03:00
|
|
|
|
#
|
2000-10-26 11:52:40 +04:00
|
|
|
|
# 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
|
|
|
|
|
#
|
2000-08-22 03:01:32 +04:00
|
|
|
|
class DocCode:
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
2000-08-27 11:12:40 +04:00
|
|
|
|
def __init__( self, margin = 0 ):
|
|
|
|
|
self.lines = []
|
|
|
|
|
self.margin = margin
|
|
|
|
|
|
|
|
|
|
def add( self, line ):
|
2000-08-22 03:01:32 +04:00
|
|
|
|
# remove margin whitespace
|
2000-08-27 11:12:40 +04:00
|
|
|
|
if string.strip( line[: self.margin] ) == "":
|
|
|
|
|
line = line[self.margin :]
|
|
|
|
|
self.lines.append( line )
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
def dump( self ):
|
2000-08-22 03:01:32 +04:00
|
|
|
|
for line in self.lines:
|
|
|
|
|
print "--" + line
|
2000-08-27 11:12:40 +04:00
|
|
|
|
print ""
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
def get_identifier( self ):
|
|
|
|
|
# this function should never be called
|
|
|
|
|
return "UNKNOWN_CODE_IDENTIFIER!!"
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
2000-08-27 11:12:40 +04:00
|
|
|
|
def dump_html( self ):
|
2000-08-22 03:01:32 +04:00
|
|
|
|
|
|
|
|
|
# clean the last empty lines
|
2000-08-27 11:12:40 +04:00
|
|
|
|
l = len( self.lines ) - 1
|
2000-10-26 11:52:40 +04:00
|
|
|
|
while l > 0 and string.strip( self.lines[l - 1] ) == "":
|
|
|
|
|
l = l - 1
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
2000-08-22 03:01:32 +04:00
|
|
|
|
print code_header
|
2000-10-26 11:52:40 +04:00
|
|
|
|
for line in self.lines[0 : l]:
|
|
|
|
|
print line
|
2000-08-22 03:01:32 +04:00
|
|
|
|
print code_footer
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
2000-08-22 03:01:32 +04:00
|
|
|
|
|
|
|
|
|
##############################################################################
|
2000-01-10 18:49:01 +03:00
|
|
|
|
#
|
2000-08-27 11:12:40 +04:00
|
|
|
|
# The DocParagraph is used to store text paragraphs
|
2000-08-22 03:01:32 +04:00
|
|
|
|
# self.words is simply a list of words for the paragraph
|
2000-01-10 18:49:01 +03:00
|
|
|
|
#
|
2000-10-26 11:52:40 +04:00
|
|
|
|
# the paragraph is filled line by line by the parser..
|
|
|
|
|
#
|
2000-08-22 03:01:32 +04:00
|
|
|
|
class DocParagraph:
|
|
|
|
|
|
2000-08-27 11:12:40 +04:00
|
|
|
|
def __init__( self ):
|
|
|
|
|
self.words = []
|
|
|
|
|
|
|
|
|
|
def add( self, line ):
|
2000-08-22 03:01:32 +04:00
|
|
|
|
# get rid of unwanted spaces in the paragraph
|
2000-08-27 11:12:40 +04:00
|
|
|
|
#
|
|
|
|
|
# the following line is the same as
|
|
|
|
|
#
|
|
|
|
|
# self.words.extend( string.split( line ) )
|
|
|
|
|
#
|
|
|
|
|
# but older Python versions don't have the `extend' attribute
|
|
|
|
|
#
|
2000-10-23 22:32:55 +04:00
|
|
|
|
last = len(self.words)
|
|
|
|
|
self.words[last:last] = string.split( line )
|
2000-10-26 11:52:40 +04:00
|
|
|
|
|
|
|
|
|
# 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!!"
|
|
|
|
|
|
2000-08-22 03:01:32 +04:00
|
|
|
|
|
2000-08-27 11:12:40 +04:00
|
|
|
|
def dump( self ):
|
2000-08-22 03:01:32 +04:00
|
|
|
|
|
2000-08-27 11:12:40 +04:00
|
|
|
|
max_width = 50
|
2000-08-22 03:01:32 +04:00
|
|
|
|
cursor = 0
|
|
|
|
|
line = ""
|
|
|
|
|
|
|
|
|
|
for word in self.words:
|
|
|
|
|
|
2000-08-27 11:12:40 +04:00
|
|
|
|
if cursor + len( word ) + 1 > max_width:
|
|
|
|
|
print line
|
|
|
|
|
cursor = 0
|
|
|
|
|
line = ""
|
2000-08-22 03:01:32 +04:00
|
|
|
|
|
2000-08-27 11:12:40 +04:00
|
|
|
|
line = line + word + " "
|
|
|
|
|
cursor = cursor + len( word ) + 1
|
|
|
|
|
|
2000-08-22 03:01:32 +04:00
|
|
|
|
if cursor > 0:
|
2000-08-27 11:12:40 +04:00
|
|
|
|
print line
|
2000-08-22 03:01:32 +04:00
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
#print "<22>" #for debugging only
|
2000-08-22 03:01:32 +04:00
|
|
|
|
|
|
|
|
|
|
2000-08-27 11:12:40 +04:00
|
|
|
|
def dump_html( self ):
|
2000-08-22 03:01:32 +04:00
|
|
|
|
|
|
|
|
|
print para_header
|
|
|
|
|
self.dump()
|
|
|
|
|
print para_footer
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
###########################################################################
|
2000-01-10 18:49:01 +03:00
|
|
|
|
#
|
2000-08-22 03:01:32 +04:00
|
|
|
|
# DocContent is used to store the content of a given marker.
|
2000-01-10 18:49:01 +03:00
|
|
|
|
#
|
2000-10-23 22:32:55 +04:00
|
|
|
|
# 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 ] ) ]
|
|
|
|
|
#
|
2000-10-26 11:52:40 +04:00
|
|
|
|
# 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..
|
|
|
|
|
#
|
2000-10-23 22:32:55 +04:00
|
|
|
|
#
|
2000-01-10 18:49:01 +03:00
|
|
|
|
class DocContent:
|
|
|
|
|
|
2000-08-27 11:12:40 +04:00
|
|
|
|
def __init__( self, lines_list ):
|
|
|
|
|
self.items = []
|
|
|
|
|
code_mode = 0
|
|
|
|
|
code_margin = 0
|
|
|
|
|
text = []
|
2000-10-26 11:52:40 +04:00
|
|
|
|
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
|
2000-08-27 11:12:40 +04:00
|
|
|
|
|
|
|
|
|
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 == '{':
|
2000-08-22 03:01:32 +04:00
|
|
|
|
|
2000-08-27 11:12:40 +04:00
|
|
|
|
if paragraph:
|
|
|
|
|
elements.append( paragraph )
|
2000-08-22 03:01:32 +04:00
|
|
|
|
paragraph = None
|
|
|
|
|
|
|
|
|
|
if line == "":
|
|
|
|
|
continue
|
|
|
|
|
|
|
|
|
|
code_mode = 1
|
|
|
|
|
code_margin = margin
|
|
|
|
|
code = None
|
|
|
|
|
continue
|
2000-08-27 11:12:40 +04:00
|
|
|
|
|
|
|
|
|
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] == "::":
|
2000-10-26 11:52:40 +04:00
|
|
|
|
|
|
|
|
|
# start a new field - complete current paragraph if any
|
2000-08-27 11:12:40 +04:00
|
|
|
|
if paragraph:
|
|
|
|
|
elements.append( paragraph )
|
2000-08-22 03:01:32 +04:00
|
|
|
|
paragraph = None
|
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
# append previous "field" to self.items
|
2000-08-27 11:12:40 +04:00
|
|
|
|
self.items.append( ( field, elements ) )
|
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
# start new field and elements list
|
2000-08-27 11:12:40 +04:00
|
|
|
|
field = words[0]
|
|
|
|
|
elements = []
|
|
|
|
|
words = words[2 :]
|
2000-10-26 11:52:40 +04:00
|
|
|
|
|
|
|
|
|
# append remaining words to current paragraph
|
2000-08-27 11:12:40 +04:00
|
|
|
|
if len( words ) > 0:
|
|
|
|
|
line = string.join( words )
|
|
|
|
|
if not paragraph:
|
|
|
|
|
paragraph = DocParagraph()
|
|
|
|
|
paragraph.add( line )
|
|
|
|
|
|
|
|
|
|
else:
|
2000-10-26 11:52:40 +04:00
|
|
|
|
# we're in code mode..
|
2000-08-27 11:12:40 +04:00
|
|
|
|
line = aline
|
|
|
|
|
|
|
|
|
|
# the code block ends with a line that has a single '}' on it
|
2000-10-26 11:52:40 +04:00
|
|
|
|
# that is located at the same column that the opening
|
|
|
|
|
# accolade..
|
2000-08-27 11:12:40 +04:00
|
|
|
|
if line == " " * code_margin + '}':
|
2000-08-22 03:01:32 +04:00
|
|
|
|
|
|
|
|
|
if code:
|
2000-08-27 11:12:40 +04:00
|
|
|
|
elements.append( code )
|
2000-08-22 03:01:32 +04:00
|
|
|
|
code = None
|
|
|
|
|
|
2000-08-27 11:12:40 +04:00
|
|
|
|
code_mode = 0
|
|
|
|
|
code_margin = 0
|
|
|
|
|
|
|
|
|
|
# otherwise, add the line to the current paragraph
|
|
|
|
|
else:
|
2000-08-22 03:01:32 +04:00
|
|
|
|
if not code:
|
|
|
|
|
code = DocCode()
|
2000-08-27 11:12:40 +04:00
|
|
|
|
code.add( line )
|
|
|
|
|
|
|
|
|
|
if paragraph:
|
|
|
|
|
elements.append( paragraph )
|
2000-08-22 03:01:32 +04:00
|
|
|
|
|
|
|
|
|
if code:
|
2000-08-27 11:12:40 +04:00
|
|
|
|
elements.append( code )
|
|
|
|
|
|
|
|
|
|
self.items.append( ( field, elements ) )
|
2000-08-22 03:01:32 +04:00
|
|
|
|
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
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!!"
|
|
|
|
|
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
2000-08-27 11:12:40 +04:00
|
|
|
|
def dump( self ):
|
|
|
|
|
for item in self.items:
|
2000-08-22 03:01:32 +04:00
|
|
|
|
field = item[0]
|
2000-08-27 11:12:40 +04:00
|
|
|
|
if field:
|
|
|
|
|
print "<field " + field + ">"
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
2000-08-27 11:12:40 +04:00
|
|
|
|
for element in item[1]:
|
2000-08-22 03:01:32 +04:00
|
|
|
|
element.dump()
|
2000-08-27 11:12:40 +04:00
|
|
|
|
|
|
|
|
|
if field:
|
|
|
|
|
print "</field> "
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
2000-08-27 11:12:40 +04:00
|
|
|
|
def dump_html( self ):
|
2000-08-22 03:01:32 +04:00
|
|
|
|
|
2000-08-27 11:12:40 +04:00
|
|
|
|
n = len( self.items )
|
2000-08-22 03:01:32 +04:00
|
|
|
|
in_table = 0
|
|
|
|
|
|
2000-08-27 11:12:40 +04:00
|
|
|
|
for i in range( n ):
|
2000-08-22 03:01:32 +04:00
|
|
|
|
item = self.items[i]
|
|
|
|
|
field = item[0]
|
|
|
|
|
|
|
|
|
|
if not field:
|
|
|
|
|
|
|
|
|
|
if in_table:
|
2000-08-27 11:12:40 +04:00
|
|
|
|
print "</td></tr></table>"
|
|
|
|
|
in_table = 0
|
2000-08-22 03:01:32 +04:00
|
|
|
|
|
|
|
|
|
for element in item[1]:
|
2000-08-27 11:12:40 +04:00
|
|
|
|
element.dump_html()
|
2000-05-31 11:54:45 +04:00
|
|
|
|
else:
|
2000-08-22 03:01:32 +04:00
|
|
|
|
if not in_table:
|
2000-05-31 11:54:45 +04:00
|
|
|
|
print "<table cellpadding=4><tr valign=top><td>"
|
2000-08-22 03:01:32 +04:00
|
|
|
|
in_table = 1
|
2000-05-31 11:54:45 +04:00
|
|
|
|
else:
|
|
|
|
|
print "</td></tr><tr valign=top><td>"
|
|
|
|
|
|
2000-08-27 11:12:40 +04:00
|
|
|
|
print "<b>" + field + "</b></td><td>"
|
2000-05-31 11:54:45 +04:00
|
|
|
|
|
2000-08-22 03:01:32 +04:00
|
|
|
|
for element in item[1]:
|
|
|
|
|
element.dump_html()
|
|
|
|
|
|
|
|
|
|
if in_table:
|
|
|
|
|
print "</td></tr></table>"
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
2000-08-27 11:12:40 +04:00
|
|
|
|
|
2000-01-10 18:49:01 +03:00
|
|
|
|
######################################################################################
|
|
|
|
|
#
|
|
|
|
|
#
|
|
|
|
|
# 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.
|
|
|
|
|
#
|
2000-10-26 11:52:40 +04:00
|
|
|
|
# "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
|
2000-01-10 18:49:01 +03:00
|
|
|
|
#
|
|
|
|
|
class DocBlock:
|
|
|
|
|
|
2000-08-27 11:12:40 +04:00
|
|
|
|
def __init__( self, block_line_list = [], source_line_list = [] ):
|
2000-10-26 11:52:40 +04:00
|
|
|
|
self.items = [] # current ( marker, contents ) list
|
|
|
|
|
self.identifier = None
|
|
|
|
|
marker = None # current marker
|
|
|
|
|
content = [] # current content lines list
|
|
|
|
|
alphanum = string.letters + string.digits + "_"
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
|
|
|
|
for line in block_line_list:
|
2000-08-27 11:12:40 +04:00
|
|
|
|
line2 = string.lstrip( line )
|
|
|
|
|
l = len( line2 )
|
|
|
|
|
margin = len( line ) - l
|
2000-10-26 11:52:40 +04:00
|
|
|
|
|
|
|
|
|
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
|
2000-08-27 11:12:40 +04:00
|
|
|
|
|
|
|
|
|
content.append( line )
|
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
if marker and content:
|
2000-08-27 11:12:40 +04:00
|
|
|
|
self.add( marker, content )
|
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
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
|
|
|
|
|
#
|
2000-01-10 18:49:01 +03:00
|
|
|
|
def add( self, marker, lines ):
|
2000-10-26 11:52:40 +04:00
|
|
|
|
|
2000-08-27 11:12:40 +04:00
|
|
|
|
# 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:
|
2000-10-26 11:52:40 +04:00
|
|
|
|
content = DocContent(lines)
|
|
|
|
|
self.items.append( ( string.lower(marker), content ) )
|
|
|
|
|
if not self.identifier:
|
|
|
|
|
self.identifier = content.get_identifier()
|
|
|
|
|
|
|
|
|
|
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
|
|
|
|
def dump( self ):
|
2000-10-26 11:52:40 +04:00
|
|
|
|
for i in range( len( self.items ) ):
|
|
|
|
|
print "[" + self.items[i][0] + "]"
|
|
|
|
|
content = self.items[i][1]
|
|
|
|
|
content.dump()
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
def dump_html( self ):
|
|
|
|
|
|
|
|
|
|
types = [ 'type', 'struct', 'functype', 'function', 'constant',
|
|
|
|
|
'enum', 'macro' ]
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
if not self.items:
|
|
|
|
|
return
|
|
|
|
|
|
|
|
|
|
# start of a block
|
|
|
|
|
print block_header
|
|
|
|
|
|
|
|
|
|
print "<h2>" + self.identifier + "</h2>"
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
# 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
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
# dump each (marker,content) element
|
|
|
|
|
for element in self.items:
|
|
|
|
|
|
|
|
|
|
marker = element[0]
|
|
|
|
|
content = element[1]
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
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
|
2000-01-10 18:49:01 +03:00
|
|
|
|
#
|
2000-10-26 11:52:40 +04:00
|
|
|
|
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 )
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
return new_list
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
2000-08-27 11:12:40 +04:00
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
# 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
|
2000-08-27 11:12:40 +04:00
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
id1 = string.lower(b1.identifier)
|
|
|
|
|
id2 = string.lower(b2.identifier)
|
|
|
|
|
if id1 < id2:
|
|
|
|
|
return -1
|
|
|
|
|
elif id1 == id2:
|
|
|
|
|
return 0
|
|
|
|
|
else:
|
|
|
|
|
return 1
|
|
|
|
|
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
def block_make_list( source_block_list ):
|
|
|
|
|
list = []
|
2000-08-27 11:12:40 +04:00
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
for block in source_block_list:
|
|
|
|
|
docblock = DocBlock( block[0], block[1] )
|
|
|
|
|
list.append( docblock )
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
return list
|
2000-08-27 11:12:40 +04:00
|
|
|
|
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
# dump a list block as a single HTML page
|
|
|
|
|
#
|
2000-05-31 11:54:45 +04:00
|
|
|
|
def dump_html_1( block_list ):
|
2000-10-26 11:52:40 +04:00
|
|
|
|
|
2000-08-22 03:01:32 +04:00
|
|
|
|
print html_header
|
|
|
|
|
|
2000-05-31 11:54:45 +04:00
|
|
|
|
for block in block_list:
|
2000-10-26 11:52:40 +04:00
|
|
|
|
block.dump_html()
|
2000-08-22 03:01:32 +04:00
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
print html_footer
|
2000-08-22 03:01:32 +04:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
|
|
|
|
|
def make_block_list():
|
|
|
|
|
"""parse a file and extract comments blocks from it"""
|
|
|
|
|
|
|
|
|
|
list = []
|
|
|
|
|
block = []
|
|
|
|
|
format = 0
|
|
|
|
|
|
|
|
|
|
# we use "format" to store the state of our parser:
|
|
|
|
|
#
|
|
|
|
|
# 0 - wait for beginning of comment
|
|
|
|
|
# 1 - parse comment format 1
|
|
|
|
|
# 2 - parse comment format 2
|
|
|
|
|
#
|
|
|
|
|
# 4 - wait for beginning of source (or comment ??)
|
|
|
|
|
# 5 - process source
|
|
|
|
|
#
|
|
|
|
|
|
|
|
|
|
comment = []
|
|
|
|
|
source = []
|
|
|
|
|
state = 0
|
|
|
|
|
|
|
|
|
|
for line in fileinput.input():
|
|
|
|
|
|
|
|
|
|
l = len( line )
|
|
|
|
|
if l > 0 and line[l - 1] == '\012':
|
|
|
|
|
line = line[0 : l - 1]
|
|
|
|
|
|
|
|
|
|
# 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
|
|
|
|
|
#
|
|
|
|
|
# unless we encounter something like:
|
|
|
|
|
#
|
|
|
|
|
# /*@.....
|
|
|
|
|
# /*#.....
|
|
|
|
|
#
|
|
|
|
|
# /* @.....
|
|
|
|
|
# /* #.....
|
|
|
|
|
#
|
|
|
|
|
if format >= 4 and l > 2 and line2[0 : 2] == '/*':
|
|
|
|
|
if l < 4 or ( line2[3] != '@' and line2[3:4] != ' @' and
|
|
|
|
|
line2[3] != '#' and line2[3:4] != ' #'):
|
|
|
|
|
list.append( ( block, source ) )
|
|
|
|
|
format = 0
|
|
|
|
|
|
|
|
|
|
if format == 0: #### wait for beginning of comment ####
|
|
|
|
|
|
|
|
|
|
if l > 3 and line2[0 : 3] == '/**':
|
|
|
|
|
i = 3
|
|
|
|
|
while i < l and line2[i] == '*':
|
|
|
|
|
i = i + 1
|
|
|
|
|
|
|
|
|
|
if i == l:
|
|
|
|
|
# this is '/**' followed by any number of '*', the
|
|
|
|
|
# beginning of a Format 1 block
|
|
|
|
|
#
|
|
|
|
|
block = []
|
|
|
|
|
source = []
|
|
|
|
|
format = 1
|
|
|
|
|
|
|
|
|
|
elif i == l - 1 and line2[i] == '/':
|
|
|
|
|
# this is '/**' followed by any number of '*', followed
|
|
|
|
|
# by a '/', i.e. the beginning of a Format 2 or 3 block
|
|
|
|
|
#
|
|
|
|
|
block = []
|
|
|
|
|
source = []
|
|
|
|
|
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 line2[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 line2[i] == '*':
|
|
|
|
|
i = i + 1
|
|
|
|
|
|
|
|
|
|
# test for the end of the block
|
|
|
|
|
if i < l and line2[i] == '/':
|
|
|
|
|
if block != []:
|
|
|
|
|
format = 4
|
|
|
|
|
else:
|
|
|
|
|
format = 0
|
|
|
|
|
else:
|
|
|
|
|
# otherwise simply append line to current block
|
|
|
|
|
block.append( line2[i:] )
|
|
|
|
|
|
|
|
|
|
continue
|
|
|
|
|
|
|
|
|
|
##############################################################
|
|
|
|
|
#
|
|
|
|
|
# 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 line2[: 2] != '/*' or line2[-2 :] != '*/':
|
|
|
|
|
if block != []:
|
|
|
|
|
format = 4
|
|
|
|
|
else:
|
|
|
|
|
format = 0
|
|
|
|
|
else:
|
|
|
|
|
# remove the start and end comment delimiters, then
|
|
|
|
|
# right-strip the line
|
|
|
|
|
line2 = string.rstrip( line2[2 : -2] )
|
|
|
|
|
|
|
|
|
|
# check for end of a format2 block, i.e. a run of '*'
|
|
|
|
|
if string.count( line2, '*' ) == l - 4:
|
|
|
|
|
if block != []:
|
|
|
|
|
format = 4
|
|
|
|
|
else:
|
|
|
|
|
format = 0
|
|
|
|
|
else:
|
|
|
|
|
# otherwise, add the line to the current block
|
|
|
|
|
block.append( line2 )
|
|
|
|
|
|
|
|
|
|
continue
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
if format >= 4: #### source processing ####
|
|
|
|
|
|
|
|
|
|
if l > 0:
|
|
|
|
|
format = 5
|
|
|
|
|
|
|
|
|
|
if format == 5:
|
|
|
|
|
source.append( line )
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
if format >= 4:
|
|
|
|
|
list.append( [block, source] )
|
|
|
|
|
|
|
|
|
|
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[0]:
|
|
|
|
|
print line
|
|
|
|
|
for line in block[1]:
|
|
|
|
|
print line
|
|
|
|
|
|
|
|
|
|
print "---------the end-----------------------"
|
2000-08-22 03:01:32 +04:00
|
|
|
|
|
|
|
|
|
|
2000-05-31 11:54:45 +04:00
|
|
|
|
|
2000-08-27 11:12:40 +04:00
|
|
|
|
def main( argv ):
|
2000-01-10 18:49:01 +03:00
|
|
|
|
"""main program loop"""
|
2000-08-27 11:12:40 +04:00
|
|
|
|
sys.stderr.write( "extracting comment blocks from sources...\n" )
|
2000-01-10 18:49:01 +03:00
|
|
|
|
list = make_block_list()
|
2000-10-26 11:52:40 +04:00
|
|
|
|
list = block_make_list(list)
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
2000-10-26 11:52:40 +04:00
|
|
|
|
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 )
|
2000-01-10 18:49:01 +03:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# If called from the command line
|
2000-08-27 11:12:40 +04:00
|
|
|
|
if __name__ == '__main__':
|
|
|
|
|
main( sys.argv )
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# eof
|