ref: d36b4a59856eb5972fe5fce39f9e43e69e8a27bd
dir: /src/tools/docmaker.py/
#!/usr/bin/env python
#
# DocMaker 0.1 (c) 2000-2001 David Turner <[email protected]>
#
# DocMaker is a very simple program used to generate the API Reference
# of programs by extracting comments from source files, and generating
# the equivalent HTML documentation.
#
# DocMaker is very similar to other tools like Doxygen, with the
# following differences:
#
# - It is written in Python (so it is slow, but easy to maintain and
# improve).
#
# - The comment syntax used by DocMaker is simpler and makes for
# clearer comments.
#
# Of course, it doesn't have all the goodies of most similar tools,
# (e.g. C++ class hierarchies), but hey, it is only 2000 lines of
# Python.
#
# DocMaker is mainly used to generate the API references of several
# FreeType packages.
#
# - David
#
import fileinput, sys, os, time, string, glob, getopt
# The Project's title. This can be overridden from the command line with
# the options "-t" or "--title".
#
project_title = "Project"
# The project's filename prefix. This can be set from the command line with
# the options "-p" or "--prefix"
#
project_prefix = ""
# The project's documentation output directory. This can be set from the
# command line with the options "-o" or "--output".
#
output_dir = None
# The following defines the HTML header used by all generated pages.
#
html_header_1 = """\
<html>
<header>
<title>"""
html_header_2= """ API Reference</title>
<basefont face="Verdana,Geneva,Arial,Helvetica">
<style content="text/css">
P { text-align=justify }
H1 { text-align=center }
LI { text-align=justify }
</style>
</header>
<body text=#000000
bgcolor=#FFFFFF
link=#0000EF
vlink=#51188E
alink=#FF0000>
<center><h1>"""
html_header_3=""" API Reference</h1></center>
"""
# This is recomputed later when the project title changes.
#
html_header = html_header_1 + project_title + html_header_2 + project_title + html_header_3
# The HTML footer used by all generated pages.
#
html_footer = """\
</body>
</html>"""
# The header and footer used for each section.
#
section_title_header = "<center><h1>"
section_title_footer = "</h1></center>"
# The header and footer used for code segments.
#
code_header = "<font color=blue><pre>"
code_footer = "</pre></font>"
# Paragraph header and footer.
#
para_header = "<p>"
para_footer = "</p>"
# Block header and footer.
#
block_header = "<center><table width=75%><tr><td>"
block_footer = "</td></tr></table><hr width=75%></center>"
# Description header/footer.
#
description_header = "<center><table width=87%><tr><td>"
description_footer = "</td></tr></table></center><br>"
# Marker header/inter/footer combination.
#
marker_header = "<center><table width=87% cellpadding=5><tr bgcolor=#EEEEFF><td><em><b>"
marker_inter = "</b></em></td></tr><tr><td>"
marker_footer = "</td></tr></table></center>"
# Source code extracts header/footer.
#
source_header = "<center><table width=87%><tr bgcolor=#D6E8FF width=100%><td><pre>"
source_footer = "</pre></table></center><br>"
# Chapter header/inter/footer.
#
chapter_header = "<center><table width=75%><tr><td><h2>"
chapter_inter = "</h2><ul>"
chapter_footer = "</ul></td></tr></table></center>"
current_section = None
# This function is used to sort the index. It is a simple lexicographical
# sort, except that it places capital letters before lowercase ones.
#
def index_sort( s1, s2 ):
if not s1:
return -1
if not s2:
return 1
l1 = len( s1 )
l2 = len( s2 )
m1 = string.lower( s1 )
m2 = string.lower( s2 )
for i in range( l1 ):
if i >= l2 or m1[i] > m2[i]:
return 1
if m1[i] < m2[i]:
return -1
if s1[i] < s2[i]:
return -1
if s1[i] > s2[i]:
return 1
if l2 > l1:
return -1
return 0
# Sort input_list, placing the elements of order_list in front.
#
def sort_order_list( input_list, order_list ):
new_list = order_list[:]
for id in input_list:
if not id in order_list:
new_list.append( id )
return new_list
# Translate a single line of source to HTML. This will convert
# a "<" into "<.", ">" into ">.", etc.
#
def html_quote( line ):
result = string.replace( line, "&", "&" )
result = string.replace( result, "<", "<" )
result = string.replace( result, ">", ">" )
return result
# same as 'html_quote', but ignores left and right brackets
#
def html_quote0( line ):
return string.replace( line, "&", "&" )
# Open the standard output to a given project documentation file. Use
# "output_dir" to determine the filename location if necessary and save the
# old stdout in a tuple that is returned by this function.
#
def open_output( filename ):
global output_dir
if output_dir and output_dir != "":
filename = output_dir + os.sep + filename
old_stdout = sys.stdout
new_file = open( filename, "w" )
sys.stdout = new_file
return ( new_file, old_stdout )
# Close the output that was returned by "close_output".
#
def close_output( output ):
output[0].close()
sys.stdout = output[1]
# Check output directory.
#
def check_output( ):
global output_dir
if output_dir:
if output_dir != "":
if not os.path.isdir( output_dir ):
sys.stderr.write( "argument" + " '" + output_dir + "' " +
"is not a valid directory" )
sys.exit( 2 )
else:
output_dir = None
def compute_time_html( ):
global html_footer
time_string = time.asctime( time.localtime( time.time() ) )
html_footer = "<p><center><font size=""-2"">generated on " + time_string + "</font></p></center>" + html_footer
# The FreeType 2 reference is extracted from the source files. These
# contain various comment blocks that follow one of the following formats:
#
# /**************************
# *
# * FORMAT1
# *
# *
# *
# *
# *************************/
#
# /**************************/
# /* */
# /* FORMAT2 */
# /* */
# /* */
# /* */
# /* */
#
# /**************************/
# /* */
# /* FORMAT3 */
# /* */
# /* */
# /* */
# /* */
# /**************************/
#
# Each block contains a list of markers; each one can be followed by
# some arbitrary text or a list of fields. Here 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 fields.
#
# Each field is simply 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.
#
# Note that markers can alternatively be written as "@MARKER:" instead of
# "<MARKER>". All marker identifiers are converted to lower case during
# parsing in order to simply sorting.
#
# 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:
#
# /*@.....*/
# /*#.....*/
# /* @.....*/
# /* #.....*/
#
#############################################################################
#
# 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, identifiers = None ):
# clean the last empty lines
#
l = len( self.lines ) - 1
while l > 0 and string.strip( self.lines[l - 1] ) == "":
l = l - 1
# The code footer should be directly appended to the last code
# line to avoid an additional blank line.
#
print code_header,
for line in self.lines[0 : l+1]:
print '\n' + html_quote(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 two lines are 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 get_words( self ):
return self.words[:]
def dump( self, identifiers = None ):
max_width = 50
cursor = 0
line = ""
extra = None
alphanum = string.lowercase + string.uppercase + string.digits + '_'
for word in self.words:
# process cross references if needed
#
if identifiers and word and word[0] == '@':
word = word[1 :]
# we need to find non-alphanumeric characters
#
l = len( word )
i = 0
while i < l and word[i] in alphanum:
i = i + 1
if i < l:
extra = word[i :]
word = word[0 : i]
block = identifiers.get( word )
if block:
word = '<a href="' + block.html_address() + '">' + word + '</a>'
else:
word = '?' + word
if cursor + len( word ) + 1 > max_width:
print html_quote0(line)
cursor = 0
line = ""
line = line + word
if not extra:
line = line + " "
cursor = cursor + len( word ) + 1
# Handle trailing periods, commas, etc. at the end of cross
# references.
#
if extra:
if cursor + len( extra ) + 1 > max_width:
print html_quote0(line)
cursor = 0
line = ""
line = line + extra + " "
cursor = cursor + len( extra ) + 1
extra = None
if cursor > 0:
print html_quote0(line)
# print "�" # for debugging only
def dump_string( self ):
s = ""
space = ""
for word in self.words:
s = s + space + word
space = " "
return s
def dump_html( self, identifiers = None ):
print para_header
self.dump( identifiers )
print para_footer
#############################################################################
#
# DocContent is used to store the content of a given marker.
#
# The "self.items" list contains (field,elements) records, where "field"
# corresponds to a given structure field 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 contents.
# y :: Even before, this field has some code contents.
# {
# 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 in 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 are 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 get_title( self ):
if self.items:
item = self.items[0]
for element in item[1]:
return element.dump_string()
# should never happen
#
return "UNKNOWN_CONTENT_TITLE!"
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, identifiers = None ):
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( identifiers )
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( identifiers )
if in_table:
print "</td></tr></table>"
def dump_html_in_table( self, identifiers = None ):
n = len( self.items )
in_table = 0
for i in range( n ):
item = self.items[i]
field = item[0]
if not field:
if item[1]:
print "<tr><td colspan=2>"
for element in item[1]:
element.dump_html( identifiers )
print "</td></tr>"
else:
print "<tr><td><b>" + field + "</b></td><td>"
for element in item[1]:
element.dump_html( identifiers )
print "</td></tr>"
#############################################################################
#
# 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.name" is a simple identifier used to uniquely identify
# the block. It is taken from the first word of the first paragraph of the
# first marker of a given block, i.e:
#
# <Type> Goo
# <Description> Bla bla bla
#
# will have a name of "Goo"
#
class DocBlock:
def __init__( self, block_line_list = [], source_line_list = [] ):
self.items = [] # current ( marker, contents ) list
self.section = None # section this block belongs to
self.filename = "unknown" # filename defining this block
self.lineno = 0 # line number in filename
marker = None # current marker
content = [] # current content lines list
alphanum = string.letters + string.digits + "_"
self.name = None
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
# now retrieve block name when possible
#
if self.items:
first = self.items[0]
self.name = first[1].get_identifier()
# This function adds 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
# are not empty
#
if l > 0 and marker:
content = DocContent( lines )
self.items.append( ( string.lower( marker ), content ) )
def find_content( self, marker ):
for item in self.items:
if ( item[0] == marker ):
return item[1]
return None
def html_address( self ):
section = self.section
if section and section.filename:
return section.filename + '#' + self.name
return "" # this block is not in a section?
def location( self ):
return self.filename + ':' + str( self.lineno )
def print_warning( self, message ):
sys.stderr.write( "WARNING:" +
self.location() + ": " + message + '\n' )
def print_error( self, message ):
sys.stderr.write( "ERROR:" +
self.location() + ": " + message + '\n' )
sys.exit()
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, identifiers = None ):
types = ['type', 'struct', 'functype', 'function',
'constant', 'enum', 'macro', 'structure', 'also']
parameters = ['input', 'inout', 'output', 'return']
if not self.items:
return
# start of a block
#
print block_header
# place html anchor if needed
#
if self.name:
print '<a name="' + self.name + '">'
print "<h4>" + self.name + "</h4>"
print "</a>"
# print source code
#
if not self.source:
print block_footer
return
lines = self.source
l = len( lines ) - 1
while l >= 0 and string.strip( lines[l] ) == "":
l = l - 1
print source_header
print ""
for line in lines[0 : l+1]:
print html_quote(line)
print source_footer
in_table = 0
# dump each (marker,content) element
#
for element in self.items:
marker = element[0]
content = element[1]
if marker == "description":
print description_header
content.dump_html( identifiers )
print description_footer
elif not ( marker in types ):
sys.stdout.write( marker_header )
sys.stdout.write( marker )
sys.stdout.write( marker_inter + '\n' )
content.dump_html( identifiers )
print marker_footer
print ""
print block_footer
#############################################################################
#
# The DocSection class is used to store a given documentation section.
#
# Each section is made of an identifier, an abstract and a description.
#
# For example, look at:
#
# <Section> Basic_Data_Types
#
# <Title> FreeType 2 Basic Data Types
#
# <Abstract>
# Definitions of basic FreeType data types
#
# <Description>
# FreeType defines several basic data types for all its
# operations...
#
class DocSection:
def __init__( self, block ):
self.block = block
self.name = string.lower( block.name )
self.abstract = block.find_content( "abstract" )
self.description = block.find_content( "description" )
self.elements = {}
self.list = []
self.filename = self.name + ".html"
self.chapter = None
# sys.stderr.write( "new section '" + self.name + "'" )
def add_element( self, block ):
# check that we don't have a duplicate element in this
# section
#
if self.elements.has_key( block.name ):
block.print_error( "duplicate element definition for " +
"'" + block.name + "' " +
"in section " +
"'" + self.name + "'\n" +
"previous definition in " +
"'" + self.elements[block.name].location() + "'" )
self.elements[block.name] = block
self.list.append( block )
def print_warning( self, message ):
self.block.print_warning( message )
def print_error( self, message ):
self.block.print_error( message )
def dump_html( self, identifiers = None ):
"""make an HTML page from a given DocSection"""
# print HTML header
#
print html_header
# print title
#
print section_title_header
print self.title
print section_title_footer
# print description
#
print block_header
self.description.dump_html( identifiers )
print block_footer
# print elements
#
for element in self.list:
element.dump_html( identifiers )
print html_footer
class DocSectionList:
def __init__( self ):
self.sections = {} # map section names to section objects
self.list = [] # list of sections (in creation order)
self.current_section = None # current section
self.identifiers = {} # map identifiers to blocks
def append_section( self, block ):
name = string.lower( block.name )
abstract = block.find_content( "abstract" )
if self.sections.has_key( name ):
# There is already a section with this name in our list. We
# will try to complete it.
#
section = self.sections[name]
if section.abstract:
# This section already has an abstract defined; simply check
# that the new section doesn't provide a new one.
#
if abstract:
section.block.print_error(
"duplicate section definition for " +
"'" + name + "'\n" +
"previous definition in " +
"'" + section.block.location() + "'\n" +
"second definition in " +
"'" + block.location() + "'" )
else:
# The old section didn't contain an abstract; we are now
# going to replace it.
#
section.abstract = abstract
section.description = block.find_content( "description" )
section.block = block
else:
# a new section
#
section = DocSection( block )
self.sections[name] = section
self.list.append( section )
self.current_section = section
def append_block( self, block ):
if block.name:
section = block.find_content( "section" )
if section:
self.append_section( block )
elif self.current_section:
self.current_section.add_element( block )
block.section = self.current_section
self.identifiers[block.name] = block
def prepare_files( self, file_prefix = None ):
# prepare the section list, by computing section filenames and the
# index
#
if file_prefix:
prefix = file_prefix + "-"
else:
prefix = ""
# compute section names
#
for section in self.sections.values():
title_content = section.block.find_content( "title" )
if title_content:
section.title = title_content.get_title()
else:
section.title = "UNKNOWN_SECTION_TITLE!"
# sort section elements according to the <order> marker if available
#
for section in self.sections.values():
order = section.block.find_content( "order" )
if order:
# sys.stderr.write( "<order> found at "
# + section.block.location() + '\n' )
order_list = []
for item in order.items:
for element in item[1]:
words = None
try:
words = element.get_words()
except:
section.block.print_warning(
"invalid content in <order> marker\n" )
if words:
for word in words:
block = self.identifiers.get( word )
if block:
if block.section == section:
order_list.append( block )
else:
section.block.print_warning(
"invalid reference to " +
"'" + word + "' " +
"defined in other section" )
else:
section.block.print_warning(
"invalid reference to " +
"'" + word + "'" )
# now sort the list of blocks according to the order list
#
new_list = order_list[:]
for block in section.list:
if not block in order_list:
new_list.append( block )
section.list = new_list
# compute section filenames
#
for section in self.sections.values():
section.filename = prefix + section.name + ".html"
self.toc_filename = prefix + "toc.html"
self.index_filename = prefix + "index.html"
# compute the sorted list of identifiers for the index
#
self.index = self.identifiers.keys()
self.index.sort( index_sort )
def dump_html_sections( self ):
for section in self.sections.values():
if section.filename:
output = open_output( section.filename )
section.dump_html( self.identifiers )
close_output( output )
def dump_html_index( self ):
output = open_output( self.index_filename )
num_columns = 3
total = len( self.index )
line = 0
print html_header
print "<center><h1>General Index</h1></center>"
print "<center><table cellpadding=5><tr valign=top><td>"
for ident in self.index:
block = self.identifiers[ident]
if block:
sys.stdout.write( '<a href="' + block.html_address() + '">' )
sys.stdout.write( block.name )
sys.stdout.write( '</a><br>' + '\n' )
if line * num_columns >= total:
print "</td><td>"
line = 0
else:
line = line + 1
else:
sys.stderr.write( "identifier '" + ident +
"' has no definition" + '\n' )
print "</tr></table></center>"
print html_footer
close_output( output )
# 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.
#
class DocChapter:
def __init__( self, block ):
self.sections_names = [] # ordered list of section names
self.sections = [] # ordered list of DocSection objects
# for this chapter
self.block = block
# look for chapter title
content = block.find_content( "title" )
if content:
self.title = content.get_title()
else:
self.title = "UNKNOWN CHAPTER TITLE"
# look for section list
content = block.find_content( "sections" )
if not content:
block.print_error( "chapter has no <sections> content" )
# compute list of section names
slist = []
for item in content.items:
for element in item[1]:
try:
words = element.get_words()
l = len( slist )
slist[l : l] = words
except:
block.print_warning(
"invalid content in <sections> marker" )
self.section_names = slist
class DocDocument:
def __init__( self ):
self.section_list = DocSectionList() # section list object
self.chapters = [] # list of chapters
self.lost_sections = [] # list of sections with
# no chapter
def append_block( self, block ):
if block.name:
content = block.find_content( "chapter" )
if content:
# a chapter definition -- add it to our list
#
chapter = DocChapter( block )
self.chapters.append( chapter )
else:
self.section_list.append_block( block )
def prepare_chapters( self ):
# check section names
#
for chapter in self.chapters:
slist = []
for name in chapter.section_names:
section = self.section_list.sections.get( name )
if not section:
chapter.block.print_warning(
"invalid reference to unknown section '" + name + "'" )
else:
section.chapter = chapter
slist.append( section )
chapter.sections = slist
for section in self.section_list.list:
if not section.chapter:
section.block.print_warning(
"section '" + section.name + "' is not in any chapter" )
self.lost_sections.append( section )
def prepare_files( self, file_prefix = None ):
self.section_list.prepare_files( file_prefix )
self.prepare_chapters()
def dump_toc_html( self ):
# dump an html table of contents
#
output = open_output( self.section_list.toc_filename )
print html_header
print "<center><h1>Table of Contents</h1></center>"
for chapter in self.chapters:
print chapter_header + chapter.title + chapter_inter
print "<table cellpadding=5>"
for section in chapter.sections:
if section.abstract:
print "<tr valign=top><td>"
sys.stdout.write( '<a href="' + section.filename + '">' )
sys.stdout.write( section.title )
sys.stdout.write( "</a></td><td>" + '\n' )
section.abstract.dump_html( self.section_list.identifiers )
print "</td></tr>"
print "</table>"
print chapter_footer
# list lost sections
#
if self.lost_sections:
print chapter_header + "OTHER SECTIONS:" + chapter_inter
print "<table cellpadding=5>"
for section in self.lost_sections:
if section.abstract:
print "<tr valign=top><td>"
sys.stdout.write( '<a href="' + section.filename + '">' )
sys.stdout.write( section.title )
sys.stdout.write( "</a></td><td>" + '\n' )
section.abstract.dump_html( self.section_list.identifiers )
print "</td></tr>"
print "</table>"
print chapter_footer
# index
#
print chapter_header + '<a href="' + self.section_list.index_filename + '">Index</a>' + chapter_footer
print html_footer
close_output( output )
def dump_index_html( self ):
self.section_list.dump_html_index()
def dump_sections_html( self ):
self.section_list.dump_html_sections()
def filter_blocks_by_type( 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
def filter_section_blocks( block ):
return block.section != None
# Perform a lexicographical comparison of two DocBlock objects. Returns -1,
# 0 or 1.
#
def block_lexicographical_compare( b1, b2 ):
if not b1.name:
return -1
if not b2.name:
return 1
id1 = string.lower( b1.name )
id2 = string.lower( b2.name )
if id1 < id2:
return -1
elif id1 == id2:
return 0
else:
return 1
# 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 file_exists( pathname ):
result = 1
try:
file = open( pathname, "r" )
file.close()
except:
result = None
return result
def add_new_block( list, filename, lineno, block_lines, source_lines ):
"""add a new block to the list"""
block = DocBlock( block_lines, source_lines )
block.filename = filename
block.lineno = lineno
list.append( block )
def make_block_list( args = None ):
"""parse a file and extract comments blocks from it"""
file_list = []
# sys.stderr.write( repr( sys.argv[1 :] ) + '\n' )
if not args:
args = sys.argv[1 :]
for pathname in args:
if string.find( pathname, '*' ) >= 0:
newpath = glob.glob( pathname )
newpath.sort() # sort files -- this is important because
# of the order of files
else:
newpath = [pathname]
last = len( file_list )
file_list[last : last] = newpath
if len( file_list ) == 0:
file_list = None
else:
# now filter the file list to remove non-existing ones
file_list = filter( file_exists, file_list )
list = []
block = []
format = 0
lineno = 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
fileinput.close()
for line in fileinput.input( file_list ):
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[2] != '@' and line2[2 : 4] != ' @' and
line2[2] != '#' and line2[2 : 4] != ' #'):
add_new_block( list, fileinput.filename(),
lineno, 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
lineno = fileinput.filelineno()
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
lineno = fileinput.filelineno()
##############################################################
#
# 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:
add_new_block( list, fileinput.filename(), lineno, 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-----------------------"
def usage():
print "\nDocMaker 0.1 Usage information\n"
print " docmaker [options] file1 [ file2 ... ]\n"
print "using the following options:\n"
print " -h : print this page"
print " -t : set project title, as in '-t \"My Project\"'"
print " -o : set output directory, as in '-o mydir'"
print " -p : set documentation prefix, as in '-p ft2'"
print ""
print " --title : same as -t, as in '--title=\"My Project\"'"
print " --output : same as -o, as in '--output=mydir'"
print " --prefix : same as -p, as in '--prefix=ft2'"
def main( argv ):
"""main program loop"""
global output_dir, project_title, project_prefix
global html_header, html_header1, html_header2, html_header3
try:
opts, args = getopt.getopt( sys.argv[1:],
"ht:o:p:",
[ "help", "title=", "output=", "prefix=" ] )
except getopt.GetoptError:
usage()
sys.exit( 2 )
if args == []:
usage()
sys.exit( 1 )
# process options
#
project_title = "Project"
project_prefix = None
output_dir = None
for opt in opts:
if opt[0] in ( "-h", "--help" ):
usage()
sys.exit( 0 )
if opt[0] in ( "-t", "--title" ):
project_title = opt[1]
if opt[0] in ( "-o", "--output" ):
output_dir = opt[1]
if opt[0] in ( "-p", "--prefix" ):
project_prefix = opt[1]
html_header = html_header_1 + project_title + html_header_2 + project_title + html_header_3
check_output( )
compute_time_html()
# we begin by simply building a list of DocBlock elements
#
list = make_block_list( args )
# now, sort the blocks into sections
#
document = DocDocument()
for block in list:
document.append_block( block )
document.prepare_files( project_prefix )
document.dump_toc_html()
document.dump_sections_html()
document.dump_index_html()
# if called from the command line
#
if __name__ == '__main__':
main( sys.argv )
# eof