updated DocMaker to generate section-specific pages
This commit is contained in:
David Turner
parent
5b939ffb77
commit
b404d06a6b
@ -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"
|
||||
|
||||
218
docs/docmaker.py
218
docs/docmaker.py
@ -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 )
|
||||
|
||||
Loading…
Reference in New Issue
Block a user