bee 0.1.0

data/lib/beedoc.rb

@@ -0,0 +1,464 @@
+# Copyright 2006 Michel Casabianca <casa@sweetohm.net>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Script to generate documentation.
+
+$:.unshift(File.join(File.dirname(__FILE__)))
+require 'bee'
+require 'erb'
+require 'fileutils'
+require 'yaml'
+
+module Bee
+
+  # Module for Bee documentation generation.
+  module Doc
+
+    # Copyright notice.
+    COPYRIGHT = 'BeeDoc version 0.1.0 (C) Michel Casabianca - 2006'
+    # Console help.
+    HELP = 'beedoc [-h] [-o dir] menu
+-h    Print help about usage and exit.
+-o    Directory where to generate documentation.
+menu  Menu file to process.'
+    # Exit value on error parsing command line
+    EXIT_PARSING_CMDLINE = 1
+    # Exit value on doc error
+    EXIT_DOC_ERROR = 2
+    # Exit value on unknown error
+    EXIT_UNKNOWN_ERROR = 3
+
+    #########################################################################
+    #                            CLASS DOCERROR                             #
+    #########################################################################
+
+    class DocError < RuntimeError; end
+
+    module DocErrorMixin
+
+      # Convenient method to raise a DocError.
+      # - message: error message.
+      def error(message)
+        raise DocError.new(message)
+      end    
+
+    end
+
+    #########################################################################
+    #                          PARSE COMMAND LINE                           #
+    #########################################################################
+
+    # Parse command line and return arguments.
+    def self.parse_command_line
+      help = false
+      output = nil
+      require 'getoptlong'
+      begin
+        opts = GetoptLong.new(['--help', '-h', GetoptLong::NO_ARGUMENT ],
+                              ['--output', '-o', GetoptLong::REQUIRED_ARGUMENT])
+        opts.each do |opt, arg|
+          case opt
+          when '--help'
+            help = true
+          when '--output'
+            output = arg
+          end
+        end
+        help = true if ARGV.length > 1
+        menu = ARGV[0]
+        return [help, output, menu]
+      end
+    end
+
+    # Run BeeDoc from command line.
+    def self.start_command_line
+      begin
+        help, output, menu = parse_command_line
+        raise "No menu file" if not menu
+      rescue
+        puts "ERROR: parsing command line (type 'beedoc -h' for help): #{$!}"
+        exit(EXIT_PARSING_CMDLINE)
+      end
+      begin        
+        if help
+          puts COPYRIGHT
+          puts HELP
+        else
+          Bee::Doc::Menu.new(menu).generate(output)
+          puts "OK"
+        end
+      rescue DocError
+        puts "ERROR: #{$!}"
+        exit(EXIT_DOC_ERROR)
+      rescue Exception => e
+        puts "ERROR: #{$!}"
+        puts e.backtrace.join("\n")
+        exit(EXIT_UNKNOWN_ERROR)
+      end
+    end      
+
+    #########################################################################
+    #                              CLASS MENU                               #
+    #########################################################################
+
+    class Menu
+
+      include DocErrorMixin
+
+      # Title for documentation.
+      attr_reader :title
+      # Generation date.
+      attr_reader :date
+      # List of menu entries.
+      attr_reader :entries
+      # Base directory.
+      attr_reader :base
+      # Contents for page being generated.
+      attr_reader :contents
+
+      # Constructor.
+      # - file: menu file to load.
+      def initialize(file)
+        begin
+          @base = File.dirname(file)
+          source = File.read(file)
+          menu = YAML::load(source)
+          @entries = []
+          error "Menu must be a list" unless menu.kind_of?(Array)
+          error "Menu description must be first entry" unless 
+            menu[0].kind_of?(Hash) and menu[0]['menu']
+          @title = menu[0]['menu']
+          @date = Time.now
+          for entry in menu[1..-1]
+            @entries << Entry.new(entry, self)
+          end
+        rescue
+          error "Error loading menu file: #{$!}"
+        end
+      end
+
+      # Generate HTML documents.
+      # - directory: where to generate documentation.
+      def generate(directory)
+        error "Destination directory '#{directory}' already exists" if
+          File.exists?(directory)
+        FileUtils.makedirs(directory)
+        write_style_sheet = false
+        for entry in @entries
+          entry.generate(directory, @date)
+          write_style_sheet = true if not entry.template
+        end
+        if write_style_sheet
+          File.open(File.join(directory, 'stylesheet.css'), 'w') do |file|
+            file.write(Entry::DEFAULT_STYLESHEET)
+          end
+        end
+      end
+
+    end
+
+    #########################################################################
+    #                             CLASS ENTRY                               #
+    #########################################################################
+
+    # A menu entry.
+    class Entry
+
+      include BuildErrorMixin
+
+      # Parent menu.
+      attr_reader :menu
+      # Title.
+      attr_reader :title
+      # File.
+      attr_reader :file
+      # Destination file.
+      attr_reader :dest
+      # Directory.
+      attr_reader :dir
+      # File type.
+      attr_reader :type
+      # Table of contents.
+      attr_reader :toc
+      # Header depth for toc.
+      attr_reader :header
+      # Template for generation.
+      attr_reader :template
+      # Generation date.
+      attr_reader :date
+
+      # Constructor.
+      # - entry: menu entry as a Hash.
+      # - menu: the root menu for the entry.
+      def initialize(entry, menu)
+        # check keys in entry
+        error "Unknown entry type '#{entry['type']}'" unless
+          ['html', 'text', 'dir', 'link'].member?(entry['type'])
+        error "A menu entry must be a Hash" unless entry.kind_of?(Hash)
+        error "'title' key is mandatory in menu entries" unless entry['title']
+        error "One of 'file' or 'dir' keys must be in a menu entry" unless
+          (entry['file'] or entry['dir']) or entry['type'] == 'link'
+        error "'file' and 'dir' keys can't be in a menu entry at the " +
+          "same time" if entry['file'] and entry['dir']
+        # save keys into fields
+        @menu = menu
+        @title = entry['title']
+        @file = entry['file']
+        @dest = entry['dest']
+        @dir = entry['dir']
+        @type = entry['type']
+        @toc = entry['toc']
+        @header = entry['header']
+        @template = entry['template']
+      end
+
+      # Generate a menu entry.
+      # - directory: destination directory.
+      # - date: generation date.
+      def generate(directory, date)
+        return if type == 'link'
+        @date = date
+        # load template
+        if @template
+          template = ERB.new(File.read(@template))
+        else
+          template = ERB.new(DEFAULT_TEMPLATE)
+        end
+        if @dir
+          # entry is a directory: copy it to destination directory
+          puts "Copying directory '#{@dir}'..."
+          FileUtils.cp_r(File.join(@menu.base, @dir), 
+                         File.join(directory, dest))
+        else
+          # entry is a regular file: generate documentation with template
+          puts "Generating '#{@dest}'..."
+          @contents = File.read(File.join(@menu.base, @file))
+          @contents = '<pre>' + escape_special_characters(@contents) + 
+            '</pre>' if text?
+          result = template.result(get_binding)
+          File.open(File.join(directory, @dest), 'w') do |file| 
+            file.write(result)
+          end
+        end        
+      end
+
+      private
+
+      # Tells if entry is a text one.
+      def text?
+        return type == 'text'
+      end
+
+      # Get a binding for ERB generation.
+      def get_binding
+        return binding
+      end
+
+      # Escape HTML special characters (such as & " ' < and >).
+      # - string: string to process.
+      # Return: processed string.
+      def escape_special_characters(string)
+        return string.gsub(/&/, '&amp;').gsub(/"/, '&quot;').
+          gsub(/'/, '&apos;').gsub(/</, '&lt;').gsub(/>/, '&gt;')
+      end
+
+      # Default ERB template to generate HTML.
+      DEFAULT_TEMPLATE = '<html>
+<head>
+<title><%= @menu.title %></title>
+<link rel="stylesheet" type="text/css" href="stylesheet.css">
+</head>
+<body marginwidth="0" marginheight="0">
+<table class="frame" width="100%" height="100%">
+<tr>
+<td class="frame" colspan="2" 
+    align="right" valign="middle"
+    height="70">
+<h1 class="title"><b><%= @menu.title %>&#xA0;&#xA0;</b></h1>
+</td>
+</tr>
+<tr>
+<td class="ruller" colspan="2" 
+    align="left" valign="middle"
+    height="10">
+<font size="-1">Generated on <%= @date.strftime("%Y-%m-%d %H:%M:%S") %></font>
+</td>
+</tr>
+<tr>
+<td class="menu"
+    align="left" valign="top"
+    width="150">
+<%
+for entry in @menu.entries
+  link = entry.dest
+  link += \'/index.html\' if entry.dir
+%>
+<a class="menu" href="<%= link %>"><%= entry.title %></a><br>
+<%
+end
+%>
+</td>
+<td class="text"
+    align="left" valign="top">
+<center><h1 class="title"><b><%= @title %></b></h1></center>
+<%= @contents %>
+</td>
+</tr>
+</table>
+</body>
+</html>'
+
+      public
+
+      # Default style sheet.
+      DEFAULT_STYLESHEET = '
+h1,h2,h3 {
+  font-family: Verdana, Helvetica, Arial, sans-serif;
+  color: #FF9000;
+}
+
+h1.title {
+  font-family: Verdana, Helvetica, Arial, sans-serif;
+  font-size: 30pt;
+  color: #000000
+}
+
+table.frame {
+  border-width: 0px;
+  border-spacing: 0px;
+}
+
+td.frame {
+  padding: 0px;
+  text-align: right;
+  border: thin solid #OOO000;
+}
+
+td.text {
+  padding: 10px;
+  font-family: Verdana, Helvetica, Arial, sans-serif;
+  font-size: 10pt;
+}
+
+td.ruller {
+  padding: 3px;
+  background-color: #000000;
+  color: #FFFFFF;
+  font-family: Verdana, Helvetica, Arial, sans-serif;
+  font-size: 10pt;
+}
+
+td.menu {
+  padding: 10px;
+  background-color: #FF9000;
+  font-family: Verdana, Helvetica, Arial, sans-serif;
+  font-size: 12pt;
+}
+
+table.toc {
+  text-align: left;
+  border-width: 0pt;
+  background-color: #F9F9F9;
+  font-family: Verdana, Helvetica, Arial, sans-serif;
+  font-size: 10pt;
+}
+
+p {
+  font-family: Verdana, Helvetica, Arial, sans-serif;
+  font-size: 10pt;
+}
+
+table {
+  font-family: Verdana, Helvetica, Arial, sans-serif;
+  font-size: 10pt;
+  border: medium solid #000000;
+  border-collapse: collapse;
+}
+
+th {
+  padding: 5px;
+  background-color: #FF9000;
+  border: thin solid #OOO000;
+  text-align: left;
+}
+
+td {
+  padding: 5px;
+  border: thin solid #OOO000;
+  text-align: left;
+}
+
+li {
+  font-family: Verdana, Helvetica, Arial, sans-serif;
+  font-size: 10pt;
+  list-style: square;
+}
+
+a:link {
+  text-decoration: none;
+  color: #FF9000;
+}
+
+a:visited  {
+  text-decoration: none;
+  color: #000000;
+}
+
+a:active {
+  text-decoration: none;
+  color: #FFFFFF;
+  background-color: #000000;
+}
+
+a:hover {
+  text-decoration: none;
+  color: #FFFFFF;
+  background-color: #000000;
+}
+
+a.menu:link {
+  text-decoration: none;
+  color: #000000;
+}
+
+a.menu:visited {
+  text-decoration: none;
+  color: #000000;
+}
+
+a.menu:active {
+  text-decoration: none;
+  color: #000000;
+}
+
+a.menu:hover {
+  text-decoration: none;
+  color: #FFFFFF;
+  background-color: #000000;
+}
+
+pre.code {
+  clear: both;
+  overflow: auto;
+  background-color: #EFEFEF;
+  padding: 0;
+  padding: 1.0em;
+}
+'
+
+    end
+
+  end
+
+end