updated DocMaker to generate section-specific pages

This commit is contained in:
David Turner 2000-12-05 14:49:39 +00:00
parent 5b939ffb77
commit b404d06a6b
2 changed files with 217 additions and 4 deletions

View File

@ -3,6 +3,9 @@
* src/base/ftsystem.c (FT_Done_Memory): fixed an obvious bug,
the ANSI "free" function was called, instead of "memory->free()"
* docs/docmaker.py: added section filtering, multi-page generation
(index page generation is still missing though)
2000-12-04 David Turner <david.turner@freetype.org>
* builds/unix/install.mk, builds/unix/ft2unix.h: the file "ft2unix.h"

View File

@ -35,6 +35,15 @@ html_footer = """
</html>
"""
section_title_header = """
<center><h1>
"""
section_title_footer = """
</h1></center>
"""
code_header = """
<font color=blue><pre>
"""
@ -55,6 +64,10 @@ source_footer = """</pre></table></center>
<br><br>
"""
current_section = None
# The FreeType 2 reference is extracted from the source files. These contain
# various comment blocks that follow one of the following formats:
#
@ -244,6 +257,16 @@ class DocParagraph:
#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 ):
print para_header
@ -390,6 +413,16 @@ class DocContent:
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]
@ -459,6 +492,7 @@ class DocBlock:
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 )
@ -494,6 +528,11 @@ class DocBlock:
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 is used to add a new element to self.items
# 'marker' is a marker string, or None
@ -520,6 +559,13 @@ class DocBlock:
if not self.identifier:
self.identifier = content.get_identifier()
def find_content( self, marker ):
for item in self.items:
if ( item[0] == marker ):
return item[1]
return None
def dump( self ):
@ -576,6 +622,163 @@ class DocBlock:
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
#
# <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")
title_content = block.find_content("title")
if title_content:
self.title = title_content.get_title()
else:
self.title = "UNKNOWN SECTION TITLE !!"
self.elements = {}
self.list = []
self.filename = self.name + ".html"
#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 ):
sys.stderr.write( "ERROR - duplicate element definition for " +
"'" + block.name + "' in section '" +
section.name + "'" )
sys.quit()
self.elements[ block.name ] = block
self.list.append( block )
def dump_html( self ):
"""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()
print block_footer
# print elements
for element in self.list:
element.dump_html()
print html_footer
class DocSectionList:
def __init__( self ):
self.sections = {}
self.list = []
self.current_section = None
def append_section( self, block ):
name = 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'll 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:
stderr.write( "ERROR - duplicate section definition" +
" for '" + name + "'" )
sys.quit()
else:
# the old section didn't contain an abstract, we're
# now going to replace it
section.abstract = abstract
section.description = block.find_content( "description" )
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:
#sys.stderr.write( " new block" )
self.current_section.add_element( block )
def dump_html_toc( self ):
# dump an html table of contents
print html_header
print "<center><h1>Table of Contents</h1></center>"
print "<center><table cellpadding=5>"
for section in self.list:
print "<tr valign=top><td>"
print '<a href="'+section.filename+'">'
print section.title
print "</a></td><td>"
section.abstract.dump_html()
print "</td></tr>"
print "</table></center>"
print html_footer
def dump_html_sections( self ):
old_stdout = sys.stdout
for section in self.sections.values():
new_file = open( section.filename, "w" )
sys.stdout = new_file
section.dump_html()
new_file.close()
sys.stdout = old_stdout
# 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
@ -807,11 +1010,18 @@ def main( argv ):
list = make_block_list()
list = block_make_list(list)
list2 = filter_blocks( list, ['type','macro','enum','constant', 'functype'] )
#list2 = list
list2.sort( block_lexicographical_compare )
section_list = DocSectionList()
for block in list:
section_list.append_block( block )
dump_html_1( list2 )
section_list.dump_html_toc()
section_list.dump_html_sections()
#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 )