docmaker.py

Branch :
Show log
Commit
Author : David Turner
Date : 2000-10-26 07:52:40
Hash : 205fc3fa
Message : 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
docs/docmaker.py
#!/usr/bin/env python
#
# DocMaker is a very simple program used to generate HTML documentation
# from the source files of the FreeType packages.
#
# 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
#

import fileinput, sys, string

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>"

block_header = """<center><hr width="550"><table width="550"><tr><td>"""
block_footer = "</table></center>"

source_header = """<center><table width="550"><tr bgcolor="#D6E8FF" width="100%"><td><pre>
"""
source_footer = """</pre></table></center>
<br><br>
"""

# 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'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..
#
# 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..
#
# 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 ):
    
        # 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 "
kc3-lang/freetype/docs/docmaker.py

Commit

kc3-lang/freetype /docs/docmaker.py
