dokkit 0.4.4 → 0.5.0

data/lib/dokkit/environment/container.rb

@@ -0,0 +1,35 @@
+#                                                                          
+# File 'container.rb' created on 15 ago 2008 at 15:16:11.                    
+#
+# See 'dokkit.rb' or +LICENSE+ for license information.                      
+#                                                                          
+# (C)2006-2008 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors). 
+#                                                                          
+
+module Dokkit
+  module Environment
+
+    class Container
+      
+      def initialize
+        @registry = { }
+        @instances = { }
+      end
+      
+      def method_missing(meth)
+        self[meth]
+      end
+      
+      def [](service_name)
+        @instances[service_name] || (@instances[service_name] = @registry[service_name].call)
+      end
+      
+      def register(service_name, &blk)
+        @instances[service_name] = nil
+        @registry[service_name] = blk
+      end
+            
+    end
+
+  end
+end

data/lib/dokkit/environment/helpers.rb

@@ -6,6 +6,7 @@
 # (C)2006-2008 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors). 
 #                                                                          
 
+require 'ostruct'
 require 'dokkit/environment/helpers/fileselection'
 require 'dokkit/environment/helpers/extmap'
 
@@ -14,7 +15,49 @@ module Dokkit
     # Collect helper class that simplify the setup of
     # documentation environment.
     module Helper
+
+      def configure(&blk)
+        
+        yield ostruct = OpenStruct.new        
+        
+        register :configuration do
+          OpenStruct.new(default_configuration.merge(ostruct.marshal_dump))
+        end
+        
+      end
       
+      def select_document(&blk)
+        
+        yield new_fs = document_fs
+                
+        register :document_fs do
+          FileSelection.new(configuration.document_dir) do |fs|
+            fs.include(*new_fs.includes)
+            fs.exclude(*new_fs.excludes)
+          end
+        end
+        
+      end
+
+      def select_data(&blk)
+
+        yield new_fs = data_fs
+
+        register :data_fs do
+          FileSelection.new(configuration.data_dir) do |fs|
+            fs.include(*new_fs.includes)
+            fs.exclude(*new_fs.excludes)
+          end    
+        end
+        
+      end
+
+      def extend_document(glob, extension)
+        FileSelection.new(configuration.document_dir).include(glob).files.each do |document_fn|
+          @extmap[document_fn] = extension
+        end
+      end
+
     end
   end
 end

data/lib/dokkit/environment/helpers/fileselection.rb

@@ -1,7 +1,7 @@
 #                                                                          
 # File 'fileselection.rb' created on 01 mag 2008 at 16:31:18.                    
 #
-# See 'dokkit.rb' or +LICENSE+ for licence information.                      
+# See 'dokkit.rb' or +LICENSE+ for license information.                      
 #                                                                          
 # (C)2006-2008 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors). 
 #                                                                          
@@ -11,6 +11,7 @@ require 'rake'
 module Dokkit
   module Environment
     module Helper
+      
       # FileSelection encapsulates the behaviour of Rake::FileList
       # class. Objects of class FileSelection are capable to return
       # the list of file in a directory. Objects are initialized with
@@ -18,8 +19,10 @@ module Dokkit
       # FileSelection#include and FileSelection#exclude instance
       # methods.
       class FileSelection
-        attr_reader :base_dir
+        
+        attr_reader :base_dir, :includes, :excludes
         alias :dir :base_dir
+        
         # Initialize a FileSelection object.
         # base_dir :: the base dir for all inclusion/exclusion operations.
         def initialize(base_dir = '.')
@@ -28,25 +31,33 @@ module Dokkit
           @excludes = []
           yield self if block_given?
         end
+        
         # Include files to the list.
         # patterns :: array of glob patterns
         def include(*patterns)
+          @includes.clear
           patterns.each { |pattern| @includes << pattern }
           self
         end
+        
         # Exclude files from the list.
         # patterns :: array of glob patterns
         def exclude(*patterns)
+          @excludes.clear
           patterns.each { |pattern| @excludes << pattern }
           self
         end
+        
         # Return an array containing the file list.
         def files
-          FileList.new(@base_dir) do |fl|
-            fl.exclude *@excludes.collect { |exclude| File.join(@base_dir, exclude) } unless @excludes.empty?
-            fl.include *@includes.collect { |include| File.join(@base_dir, include) } unless @includes.empty?
-          end.uniq.select { |fn| not File.directory?(fn) }
+          if File.exists?(@base_dir)  
+            FileList.new(@base_dir) do |fl|
+              fl.exclude *@excludes.collect { |exclude| File.join(@base_dir, exclude) } unless @excludes.empty?
+              fl.include *@includes.collect { |include| File.join(@base_dir, include) } unless @includes.empty?
+            end.uniq.select { |fn| not File.directory?(fn) }
+          end
         end
+      
       end
     end
   end

data/lib/dokkit/factory/factory.rb

@@ -27,11 +27,11 @@ module Dokkit
     #
     # Example:
     # 
-    # factory.add(:bar => bar_factory_method) # add a method that
-    #                                         # instantiates Bar object
+    # factory.add(:bar) { Bar.new } # add a method that
+    #                               # instantiates Bar object
     #
-    def add(factory_method)
-      @methods.merge! factory_method
+    def add(key, &factory_method)
+      @methods[key] = factory_method
     end
 
     # Construct an instance for the given class. Note that, if an

data/lib/dokkit/filters.rb

@@ -12,3 +12,4 @@ require 'dokkit/filters/deplate'
 require 'dokkit/filters/maruku'
 require 'dokkit/filters/tidy'
 require 'dokkit/filters/haml'
+require 'dokkit/filters/yaml'

data/lib/dokkit/filters/maruku.rb

@@ -18,7 +18,15 @@ module Dokkit
       end
       
     end
-    
+
+    class MarukuLatex
+      
+      def filter(text)
+        Maruku.new(text).to_latex
+      end
+      
+    end
+
   end
 end
 

data/lib/dokkit/filters/yaml.rb

@@ -0,0 +1,26 @@
+#                                                                          
+# File 'yaml.rb' created on 18 ago 2008 at 14:56:12.                    
+#
+# See 'dokkit.rb' or +LICENSE+ for license information.                      
+#                                                                          
+# (C)2006-2008 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors). 
+#                                                                          
+
+require 'yaml'
+
+module Dokkit
+  module Filter
+    class YAML
+      
+      def initialize(document)
+        @document = document
+      end
+      
+      def filter(text)
+        @document.configuration.recursive_merge! ::YAML::load(text)
+        nil
+      end
+      
+    end
+  end
+end

data/lib/dokkit/logging.rb

@@ -1,7 +1,7 @@
 #                                                                          
 # File 'logging.rb' created on 04 mag 2008 at 17:39:01.                    
 #
-# See 'dokkit.rb' or +LICENSE+ for licence information.                      
+# See 'dokkit.rb' or +LICENSE+ for license information.                      
 #                                                                          
 # (C)2006-2008 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors). 
 #                                                                          

data/lib/dokkit/resource/document.rb

@@ -6,6 +6,8 @@
 # (C) 2006, 2007, 2008 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors).
 #
 
+require 'rubygems'
+
 require 'yaml'
 require 'erb'
 require 'dokkit/hash'
@@ -18,140 +20,58 @@ module Dokkit
     # instances are usually created on demand by
     # Dokkit::Resource::Factory.
     class Document
-      include FilenameHelper
-      
-      # Includes the builtin extensions to be used by Document objects.
-      include Extension::Builtin
+      include FilenameHelper, Extension::Builtin
+
+      attr_accessor :logger, :cache, :resource_factory, :filter_factory
       
-      attr_reader :source_fn
-      attr_reader :basename, :name_noext, :dirname, :relativename
-      attr_reader :config_fns, :layout_fns, :target_fns
-      attr_reader :targets, :layouts, :deps
-      attr_reader :default_config_ext, :default_format, :default_formatter
-      attr_accessor :configuration, :default_configuration_value
+      attr_reader :source_fn, :env_configuration, :configuration
+      attr_reader :configs, :targets, :layouts, :deps
+      attr_reader :formatter, :format
       
       # Initialize a Document instance.
       # +source_fn+:: is the file name of the document source file.
       # +configuration+:: is the configuration hash to be associated with the document.
       # +logger+:: is the logger instance.
       # +cache+:: is the cache manager instance.
-      def initialize(source_fn, configuration, logger, cache, resource_factory, filter_factory, &blk)
-        @source_fn, @logger, @cache, @resource_factory, @filter_factory = source_fn, logger, cache, resource_factory, filter_factory
-        @config_fns = []
-        @targets = { }
-        @layouts = { }
-        @deps = { }
-
-        # Get basename stripping out path and extension from +source_fn+
-        @basename = File.basename(source_fn, File.extname(source_fn))
-
-        # Get the directory part of source_fn
-        @dirname = File.dirname(source_fn)
+      def initialize(source_fn, env_configuration, &blk)
+        @source_fn = source_fn
+        @env_configuration = env_configuration
 
-        # Set the document name with path but without extension
-        @name_noext = File.join(@dirname, @basename)
-
-        # Get name relative to configuration.document_dir
-        @relativename = filename_helper(@name_noext, configuration[:document_dir], '')
-
-        # Set default configuration file extension
-        @default_config_ext = '.yaml'
-        # Set default output format
-        @default_format = 'html'
-        # Set default input formatter format
-        @default_formatter = 'deplate'
+        reconfigure(&blk)
+      end
+      
+      def config(config_fn)
+        reconfigure('config' => config_fn)
+      end
+      
+      def layout(layout_fn)
+        reconfigure('layout' => layout_fn)  
+      end
+      
+      def reconfigure(configuration = { }, &blk)
+        init_default(configuration)
 
-        @default_configuration_value = 'not defined'
-        
-        # yield self to an optional configuration block
         yield self if block_given?
         
-        # Setup hashes
-        setup_header_configuration
-        @configuration = configuration.recursive_merge('layout' => @relativename)
-        setup_targets(@default_format)
-        
-        # Configure the document
         configure
-        
-        @formatter = @configuration['formatter'] || @default_formatter
-
-        collect_all
       end
       
-      def method_missing(meth)
-        if @configuration.has_key?(meth.to_s)
-          @configuration[meth.to_s]
-        else
-          @logger.warn("Configuration key '#{meth.to_s}' is not defined for #{source_fn}.")
-          @default_configuration_value
-        end
-      end
-
       def get_binding
         binding
       end
       
-      # Read the configuration file +fn+ and return:
-      # * the resulting configuration hash
-      # * an array containing the names of the read config files
-      # If +fn+ contains configuration data in the
-      # header then this method extract it. Note that the method read
-      # *recursively* the configuration file specified in config key
-      # loading it from config_dir folder.
-      # For example:
-      #
-      # ---
-      # key: value
-      # config: required
-      #
-      #
-      # The resulting configuration hash will be the key/value pair
-      # *plus* the configuration in +config_dir/required.yaml+.
-      def add_config(fn)
-        File.exists?(fn) ? merge_configuration_file(fn) : @logger.error("Configuration file '#{fn}' not found for '#{@source_fn}'!")
-      end
-
-      def add_layout(name, format = @default_format)
-        if File.exists?(get_layout_filename(name, format))
-          @layouts[format] << get_layout_filename(name, format)
-        else
-          @logger.warn("Layout file '#{get_layout_filename(name, format)}' does not exists for '#{source_fn}'!")
-        end
-      end
-
-      def default_filter_chain_for(formatter, format)
-        if @configuration[:default_filter_chain][formatter].has_key?(format)
-          @configuration[:default_filter_chain][formatter][format]
-        else
-          @logger.error("Output format '#{format}' is not available for '#{formatter}' formatter.")
-        end
-      end
-
-      def default_postfilter_chain_for(format)
-        @configuration[:default_postfilter_chain][format]
-      end
-
       def has_format?(format)
         @targets.has_key?(format)
       end
       
       # Return the filters chain associated with the given formatter and output format.
-      def filters_for(formatter, format)
-        if has_format?(format)
-          process_filter_key('filter', format, default_filter_chain_for(formatter, format))
-        else
-          default_filter_chain_for(formatter, format)
-        end
+      def filters_for(format, formatter = @formatter)
+        process_filter_key('filter', format) || default_filter_chain_for(formatter, format)
       end
 
       # Return the post filters chain associated with the given format.
       def post_filters_for(format)
-        if has_format?(format)
-          process_filter_key('postfilter', format, default_postfilter_chain_for(format))
-        else
-          default_postfilter_chain_for(format)
-        end
+        process_filter_key('postfilter', format) || default_postfilter_chain_for(format)
       end
 
       def target_for(format)
@@ -162,32 +82,104 @@ module Dokkit
         @deps[format]
       end
 
-      def current_format
+      def format
         @current_format || @default_format
       end
-            
+
+      def render?
+        if @configuration.has_key?('render')
+          return false unless @configuration['render']
+        end
+        true
+      end
+
       # Render the document in the specified format.
       def render(args = { })
-        @current_format = args[:format]
-        args = { :format => @default_format }.merge args
-        if args.has_key?(:document)
-          document = @resource_factory.get(:document, args[:document])
-          @cache.add_dependency(source_fn, args[:format], document.source_fn)
-          document.render(:format => args[:format])
+        if args[:format].nil?
+          unless @current_format
+            args = { :format => @default_format }.merge args
+            @current_format = args[:format]          
+          end
         else
-          do_render!(@formatter, args[:format])
+          @current_format = args[:format]
         end
+        args.has_key?(:partial) ? render_partial(args[:partial], @current_format) : do_render!(@formatter, @current_format)
       end
       
       # Return the content of the source document file.
       def source
         @source ||= read_source
       end
-            
+      
       private
 
-      def process_filter_key(key, format, default_filter_chain)
-        @targets[format].has_key?(key) ? @targets[format][key] : default_filter_chain
+      def method_missing(meth)
+        if @configuration.has_key?(meth.to_s)
+          @configuration[meth.to_s]
+        else
+          @logger.warn("Configuration key '#{meth.to_s}' is not defined for #{source_fn}.")
+          @default_configuration_value
+        end
+      end
+
+      def init_default(configuration)
+        @configs = []
+        @targets = { }
+        @layouts = { }
+        @deps = { }
+        
+        @default_config_ext = '.yaml'
+        @default_format = 'html'
+        @default_formatter = 'deplate'
+        @default_configuration_value = 'not defined'
+        @configuration = { 'layout' => relative_name }.merge configuration
+        @configuration['render'] = false if basename =~ /^_/
+      end
+      
+      # Get basename stripping out path and extension from +source_fn+
+      def basename
+        File.basename(source_fn, File.extname(source_fn))
+      end
+
+      # Get the directory part of source_fn
+      def dirname
+        File.dirname(source_fn)
+      end
+
+      def name_noext
+        File.join(dirname, basename)
+      end
+
+      # Get name relative to configuration.document_dir
+      def relative_name
+        filename_helper(name_noext, @env_configuration[:document_dir], '')        
+      end
+
+      def add_config(fn)
+        File.exists?(fn) ? merge_configuration_file(fn) : @logger.error("Configuration file '#{fn}' not found for '#{@source_fn}'!")
+      end
+
+      def add_layout(name, format = @default_format)
+        if File.exists?(get_layout_filename(name, format))
+          @layouts[format] << get_layout_filename(name, format)
+        else
+          @logger.debug("Layout file '#{get_layout_filename(name, format)}' does not exist for '#{source_fn}'.")
+        end
+      end
+
+      def default_filter_chain_for(formatter, format)
+        @env_configuration[:default_filter_chain][formatter][format]        
+      end
+
+      def default_postfilter_chain_for(format)
+        @env_configuration[:default_postfilter_chain][format]
+      end
+      
+      # @logger.error("Output format '#{format}' is not available for '#{formatter}' formatter.")
+      # @logger.error("Formatter '#{formatter}' is not available.")
+      
+      def process_filter_key(key, format)
+        @targets.has_key?(format) ? @targets[format][key] : nil
       end
 
       # Read the content of the source document file from disk.
@@ -200,7 +192,7 @@ module Dokkit
       end
 
       def load_config_file(fn)
-        config_fn = File.join(@configuration[:config_dir], fn)
+        config_fn = File.join(@env_configuration[:config_dir], fn)
         config_fn += @default_config_ext if File.extname(config_fn).empty?
         @configuration.delete('config')
         add_config(config_fn)
@@ -208,7 +200,7 @@ module Dokkit
       
       def merge_configuration_file(fn)
         fn == @source_fn ? @configuration.recursive_merge!(@header_configuration) : @configuration.recursive_merge!(YAML::load_file(fn))
-        @config_fns << fn
+        @configs << fn
         process_config_configuration_key if @configuration.has_key?('config')
       end
       
@@ -223,24 +215,27 @@ module Dokkit
       
       # Render document in the given format.
       def do_render!(formatter, format)
-        if @targets[format]
-          render_source!(formatter, format)
-          render_all_layouts!(format)
-        else
-          @logger.error("Don't know how to render '#{source_fn}': format '#{format}' is unknown.")
-        end
+        render_source!(formatter, format)
+        render_all_layouts!(format)
         @content_for_layout
       end
       
       # Produce output from source.
       def render_source!(formatter, format)
-        @content_for_layout = apply_filters(@source, filters_for(formatter, format), format) unless @source.nil?
+        @content_for_layout = apply_filters(@source, filters_for(format, formatter), format) unless @source.nil?
       end
       
       def render_layout!(layout_fn, format)
         @content_for_layout = apply_filters(File.read(layout_fn), post_filters_for(format), format) unless File.read(layout_fn).nil?
       end
 
+      def render_partial(source_fn, format)
+        basename, dirname  = '_' + File.basename(source_fn), File.dirname(source_fn)
+        partial_fn = File.join(@env_configuration[:document_dir], File.join(dirname, basename))
+        @cache.add_dependency(@source_fn, format, partial_fn)
+        @resource_factory.get(:document, partial_fn).render(:format => format)
+      end
+      
       # Injects rendered content from +source_fn+ in the layout chain.
       def render_all_layouts!(format)
         @layouts[format].each { |layout_fn| render_layout!(layout_fn, format) } unless !@layouts[format] || @layouts[format].empty?
@@ -260,10 +255,18 @@ module Dokkit
       # 3. configuration in COMMON.yaml file (or files) exist.
       # 4. configuration in doc/configs/+basename+.yaml if file exists.
       def configure # :doc:
+        setup_header_configuration
+        setup_targets(@default_format)
+
         add_config(config_fn_relative_to(:config_dir)) if File.exists?(config_fn_relative_to(:config_dir))
         add_common_config
         add_config(config_fn_relative_to(:document_dir)) if File.exists?(config_fn_relative_to(:document_dir))
         add_config(@source_fn) if @header_configuration
+        
+        @formatter = @configuration['formatter'] || @default_formatter
+        
+        collect_all
+        @configuration
       end
       
       # Collect the layout files traversing +targets+ hash.
@@ -284,7 +287,7 @@ module Dokkit
       end
 
       def get_layout_filename(name, format)
-        File.join(@configuration[:layout_dir], name + ".#{format.to_s}")
+        File.join(@env_configuration[:layout_dir], name + ".#{format.to_s}")
       end
       
       # Process +format+ key in configuration hash.
@@ -300,14 +303,10 @@ module Dokkit
       def process_format_configuration_key(format)
         format_key = format.keys.first
         opts = format.values.first
-        if opts
-          ext = (opts['ext'] if opts.has_key?('ext')) || format_key
-          filters =  (opts['filter'] if opts.has_key?('filter')) || default_filter_chain_for(@formatter, 'html')
-          post_filters = (opts['postfilter'] if opts.has_key?('postfilter')) || default_postfilter_chain_for('html')
-          { :target_fn => target_fn(ext.to_sym), 'filter' => filters, 'postfilter' => post_filters }
-        else
-          @logger.error("You must define format '#{format}'!")
-        end
+        ext = (opts['ext'] if opts.has_key?('ext')) || format_key
+        filters =  (opts['filter'] if opts.has_key?('filter')) || default_filter_chain_for(@formatter, 'html')
+        post_filters = (opts['postfilter'] if opts.has_key?('postfilter')) || default_postfilter_chain_for('html')
+        { :target_fn => target_fn(ext.to_sym), 'filter' => filters, 'postfilter' => post_filters }
       end
       
       # Iterates through configuration +:targets+ key (if
@@ -321,7 +320,7 @@ module Dokkit
         @targets.each do |format, target|
           @deps[format] = []
           @deps[format] << @source_fn # the essential dependency from source file
-          @deps[format].concat @config_fns # dependency from configuration files
+          @deps[format].concat @configs # dependency from configuration files
           @deps[format].concat @layouts[format] if @layouts.has_key?(format) # dependency from layout files
           @deps[format].concat @cache.deps[source_fn][format] if @cache.deps[source_fn] and @cache.deps[source_fn][format]
           @deps[format].uniq! # remove duplicates
@@ -340,7 +339,7 @@ module Dokkit
       
       # Configure from commons configuration files.
       def add_common_config
-        resolve_common_configs(@dirname).reverse.each do |file|
+        resolve_common_configs(dirname).reverse.each do |file|
           add_config(file)
         end
       end
@@ -362,7 +361,7 @@ module Dokkit
       # config_fn #=> 'doc/configs/subdir/document.yaml'
       #
       def config_fn_relative_to(dir_config_key)
-        filename_helper(@name_noext, @configuration[:document_dir], @configuration[dir_config_key], @default_config_ext)
+        filename_helper(name_noext, @env_configuration[:document_dir], @env_configuration[dir_config_key], @default_config_ext)
       end
       
       # Return target filename for a given format.
@@ -370,11 +369,11 @@ module Dokkit
       # Example:
       #
       # source_fn = 'doc/pages/document.ext'
-      # format = :html
+      # format = 'html'
       # target_fn(format) #=> 'output/document.html'
       #
       def target_fn(format)
-        filename_helper(@name_noext, @configuration[:document_dir], @configuration[:output_dir], ".#{format.to_s}")
+        filename_helper(name_noext, @env_configuration[:document_dir], @env_configuration[:output_dir], ".#{format.to_s}")
       end
       
       # Apply filters on text to produce the given format.