dokkit 0.3.0 → 0.4.0

data/lib/dokkit/resource/extensions/builtin.rb

@@ -0,0 +1,19 @@
+#                                                                          
+# File 'builtin.rb' created on 21 giu 2008 at 20:41:42.                    
+#
+# See 'dokkit.rb' or +LICENSE+ for licence information.                      
+#                                                                          
+# (C)2006-2008 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors). 
+#                                                                          
+
+require 'dokkit/resource/extensions/html'
+
+module Dokkit
+  module Resource
+    module Extension
+      module Builtin
+        include HTML
+      end
+    end
+  end
+end

data/lib/dokkit/resource/extensions/html.rb

@@ -0,0 +1,22 @@
+#                                                                          
+# File 'html.rb' created on 21 giu 2008 at 19:55:48.                    
+#
+# See 'dokkit.rb' or +LICENSE+ for licence information.                      
+#                                                                          
+# (C)2006-2008 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors). 
+#                                                                          
+
+require 'dokkit/resource/extensions/url'
+
+module Dokkit
+  module Resource
+    module Extension
+      module HTML
+        include Url
+        def link_to(name, args = { })
+          "<a href=\"#{relative(args[:href])}\" class=\"#{args[:class]}\">#{name}</a>"
+        end
+      end
+    end
+  end
+end

data/lib/dokkit/resource/extensions/url.rb

@@ -0,0 +1,25 @@
+#                                                                          
+# File 'url.rb' created on 09 mag 2008 at 19:13:53.                    
+#
+# See 'dokkit.rb' or +LICENSE+ for licence information.                      
+#                                                                          
+# (C)2006-2008 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors). 
+#                                                                          
+
+module Dokkit
+  module Resource
+    module Extension
+      module Url
+        def relative(href)
+          thr = href
+          if thr.is_a?(String) && href[0,1] == '/'     
+            dtfn = File.dirname(source_fn[/^#{configuration[:document_dir]}\/(.*)/,1]) + '/'
+            count = dtfn == './' ? 0 : dtfn.split('/').length
+            thr = ('../' * count) + href[1..href.length]
+          end        
+          thr
+        end      
+      end
+    end
+  end
+end

data/lib/dokkit/{filters/base.rb → resource/extensions.rb}

@@ -1,18 +1,17 @@
 #                                                                          
-# File 'base.rb' created on 15 feb 2008 at 22:56:37.                    
+# File 'extension.rb' created on 09 mag 2008 at 19:12:50.                    
 #
 # See 'dokkit.rb' or +LICENSE+ for licence information.                      
 #                                                                          
-# (C) 2008 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors). 
+# (C)2006-2008 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors). 
 #                                                                          
 
+require 'dokkit/resource/extensions/url'
+
 module Dokkit
-  module Filters
-    class Base
-      def filter(text)
-        nil
-      end
+  module Resource
+    module Extension
+      
     end
   end
 end
-

data/lib/dokkit/resource/filenamehelper.rb

@@ -0,0 +1,28 @@
+#                                                                          
+# File 'filenamehelper.rb' created on 21 apr 2008 at 14:25:47.                    
+#
+# See 'dokkit.rb' or +LICENSE+ for licence information.                      
+#                                                                          
+# (C) 2006, 2007, 2008 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors). 
+#                                                                          
+
+module Dokkit
+  module Resource
+    # This is a helper module that aims to simplify operation with
+    # filenames.
+    module FilenameHelper
+      # Return a filename transformed in its directory part and
+      # (optionally) in its extension.
+      # +fn+:: is the source filename.
+      # +dir+:: is the directory part to be changed.
+      # +new_dir+:: is the new directory part that substitutes +dir+.
+      # +new_ext+:: is the (optionally) new extension for the +fn+.
+      def filename_helper(fn, dir, new_dir, new_ext = '')
+        ext = File.extname(fn).sub(/^\./,'') # strip leading dot
+        new_fn = fn.sub(/#{dir}/, new_dir)
+        new_fn = new_fn << new_ext unless new_ext.empty?
+        new_fn
+      end    
+    end
+  end
+end

data/lib/dokkit/resource.rb

@@ -0,0 +1,11 @@
+#                                                                          
+# File 'resource.rb' created on 04 mag 2008 at 17:41:25.                    
+#
+# See 'dokkit.rb' or +LICENSE+ for licence information.                      
+#                                                                          
+# (C)2006-2008 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors). 
+#                                                                          
+
+require 'dokkit/resource/document'
+require 'dokkit/resource/data'
+

data/lib/dokkit/tasklib/clean.rb

@@ -0,0 +1,73 @@
+#                                                                          
+# File 'clean.rb' created on 14 apr 2008 at 16:04:19.                    
+#
+# See 'dokkit.rb' or +LICENSE+ for licence information.                      
+#                                                                          
+# (C) 2008 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors). 
+#                                                                          
+
+module Dokkit
+  module TaskLib
+    # The Clean task library is a collection of rake tasks devoted to
+    # the cleaning of the documentation environment. The library
+    # defines a clean:output that remove the generated output folder
+    # (if exists). It defines also a clean:cache task that remove the
+    # cache folder (if exists).
+    class Clean
+      attr_reader :output_dir, :cache_dir
+      
+      # Initialize the library with the logger instance, an optional
+      # namespace and configuration hash.
+      def initialize(logger, configuration, namespace = 'clean')
+        @namespace = namespace
+        @logger = logger
+        @configuration = configuration
+        @output_dir = configuration[:output_dir]
+        @cache_dir = configuration[:cache_dir]
+        define_tasks
+      end
+      
+      private
+      
+      # Define library tasks under the given namespace.
+      def define_tasks
+        namespace @namespace do
+          define_output_task
+          define_cache_task
+          define_clean_all_task
+        end
+      end
+      
+      # Define a task to remove output directory.
+      def define_output_task
+        desc "Remove the generated output."
+        task :output do
+          remove_dir(output_dir)
+        end
+      end
+      
+      # Define a task to remove cache directory.
+      def define_cache_task
+        desc "Remove cache directory."
+        task :cache do
+          remove_dir(cache_dir)
+        end
+      end
+      
+      def remove_dir(dir)
+        if File.exists?(dir)
+          @logger.info("Removing directory '#{dir}'.")
+          rm_rf dir unless dir == '.'
+        end        
+      end
+      
+      # Define a task that clean the documentation environment
+      # removing both output and cache directory.
+      def define_clean_all_task
+        desc "Clean the documentation environment."
+        task :all => ["#{@namespace}:output", "#{@namespace}:cache"]
+      end
+      
+    end
+  end
+end

data/lib/dokkit/tasklib/render.rb

@@ -0,0 +1,137 @@
+#                                                                          
+# File 'render.rb' created on 18 feb 2008 at 17:47:44.                    
+#
+# See 'dokkit.rb' or +LICENSE+ for licence information.                      
+#                                                                          
+# (C) 2008 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors). 
+#                                                                          
+
+require 'rake/tasklib'
+
+module Dokkit
+  module TaskLib
+    # Render task library defines a set of rake tasks devoted to the
+    # transformation (rendering) of the documents and data files.
+    class Render < Rake::TaskLib
+      
+      # Initialize a set of tasks that transform resources.
+      # +namespace+:: is the namespace for the tasks defined in the library.
+      # +logger+:: is the logger instance.
+      # +factory+:: is a factory class that creates document instances. 
+      # +document_fns+:: is an array of source filenames.  
+      # +data_fns+:: is an array of data files.       
+      def initialize(logger, resource_factory, document_fns, data_fns, namespace = 'render')
+        @namespace = namespace
+        @document_fns = document_fns
+        @data_fns = data_fns
+        @resource_factory = resource_factory
+        @logger = logger
+        define_tasks
+      end
+      
+      # Use factory to get an instance of Dokkit::Resource::Document
+      # starting from document filename.
+      def get_document(document_fn)
+        @resource_factory.get(:document, document_fn)  
+      end
+      
+      # use factory to get an instance of Dokkit::Resource::Data
+      # starting from data filename. Note that Data instances are
+      # *immutable* resources, that is no rendering process occurs:
+      # the file is copied as is.
+      def get_data(data_fn)
+        @resource_factory.get(:data, data_fn)
+      end
+
+      private
+      
+      # Create output directory +dn+ unless it already exists.
+      def mkdir(dn)
+        mkdir_p(dn, :verbose => false) unless File.exists?(dn)
+      end
+      
+      # Write the result of the rendering to the target file. The
+      # output directory is created at this time.
+      def write_document(render_text, target_fn)
+        mkdir(File.dirname(target_fn))
+        File.open(target_fn, 'w') { |file| file << render_text }
+      end
+      
+      # Copy the given source data file to the given target destination.
+      def write_data(data)
+        mkdir(File.dirname(data.target_fn))
+        cp(data.source_fn, data.target_fn, :preserve => true, :verbose => false)
+      end
+      
+      # Define all tasks in library.
+      def define_tasks
+        namespace @namespace do
+          define_render_all_documents_task
+          define_data_task
+          define_render_all_task
+        end
+      end
+      
+      # Define render all documents task.
+      def define_render_all_documents_task
+        desc "Render documents."
+        task :doc do
+          render_all_documents
+        end
+      end
+      
+      def render_all_documents
+        @document_fns.each { |fn| render_all_targets(get_document(fn)) }  
+      end
+      
+      def render_all_targets(document)
+        document.targets.each_key do |format|
+          render_target(document, format) if need_update?(document.target_for(format), document.deps_for(format))
+        end
+      end
+      
+      def render_target(document, format)
+        @logger.info("Render '#{document.source_fn}' => '#{document.target_for(format)}'.")
+        write_document(document.render(:format => format), document.target_for(format))
+      end
+       
+      # Define data task.
+      def define_data_task
+        desc "Copy data files."
+        task :data do
+          copy_all_data
+        end
+      end
+      
+      def copy_all_data
+        @data_fns.each { |fn| copy_data(get_data(fn)) }
+      end
+       
+      def copy_data(data)
+        if need_update?(data.target_fn, data.source_fn)
+          @logger.info("Copy '#{data.source_fn}' => '#{data.target_fn}'.")
+          write_data(data)
+        end
+      end
+      
+      # Define a task that render all documents and copy all data.
+      def define_render_all_task
+        desc "Render the documents and copy the data."
+        task :all => ["#{@namespace}:doc", "#{@namespace}:data"]
+      end
+      
+      private
+      
+      # Compares target mtime against dependencies mtime. Returns true
+      # if target mtime is greater than dependencies mtime returns
+      # true. Otherwise return false (target needs update).
+      def need_update?(target, deps)
+        return true unless File.exists?(target)
+        deps.each { |dep| return true if File.mtime(target) < File.mtime(dep) }
+        false
+      end
+      
+    end
+  end
+end
+

data/lib/dokkit/tasklib.rb

@@ -0,0 +1,11 @@
+#                                                                          
+# File 'tasklib.rb' created on 04 mag 2008 at 17:40:50.                    
+#
+# See 'dokkit.rb' or +LICENSE+ for licence information.                      
+#                                                                          
+# (C)2006-2008 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors). 
+#                                                                          
+
+require 'dokkit/tasklib/render'
+require 'dokkit/tasklib/clean'
+

data/lib/dokkit.rb

@@ -1,36 +1,39 @@
 # dokkit.rb - main Dokkit module  
 
 #####
-## *Dokkit* is a Rote (http://rote.rubyforge.it) and Rake (http://rake.rubyforge.org) 
-## based documentation building tool. It uses the deplate rendering engine to produce
-## very polished tex file, page-based documentation, websites, and general textual templates.
-## It enables embedded Ruby code, layouts, YAML config files and rake tasks
-## to be used to automatically generate output in any
-## (textual) format from a directory tree containing template files.
+## *Dokkit* is a rake (http://rake.rubyforge.org) based documentation
+## building tool. It uses filters to produce very polished tex file,
+## page-based documentation, websites, and general textual templates.
+## It enables embedded ruby code, layouts, YAML config files and rake
+## tasks to be used to automatically generate output in any (textual)
+## format from a directory tree containing template files.
 ##
-## Dokkit was created to manage the documentation produced by Alca Coop (http://alca.le.it/) for its customers
-## and it is a fairly flexible tool.
+## Dokkit was created to manage the documentation produced by Alca
+## Coop (http://alca.le.it/) for its customers and it is a fairly
+## flexible tool.
 ##
-## Dokkit can be used from the command-line, or in your own +Rakefile+. It
-## supports both manual and automatic rendering of modified resources, and
-## can be configured to monitor your source tree for changes.
+## Dokkit can be used from the command-line, or in your own
+## +Rakefile+. It supports both manual and automatic rendering of
+## modified resources.
 ##
-## See +README+ and http://dokkit.rubyforge.org for general usage information.
+## See +README+ and http://dokkit.rubyforge.org for general usage
+## information.
 ##
-## Copyright (C) 2006, 2007  Andrea Fazzi (and contributors).
+## Copyright (C) 2006, 2007, 2008  Andrea Fazzi (and contributors).
 ##
-## This program is free software: you can redistribute it and/or modify
-## it under the terms of the GNU General Public License as published by
-## the Free Software Foundation, either version 3 of the License, or
-## (at your option) any later version.
+## This program is free software: you can redistribute it and/or
+## modify it under the terms of the GNU General Public License as
+## published by the Free Software Foundation, either version 3 of the
+## License, or (at your option) any later version.
 ##
-## This program is distributed in the hope that it will be useful,
-## but WITHOUT ANY WARRANTY; without even the implied warranty of
-## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-## GNU General Public License for more details.
+## This program is distributed in the hope that it will be useful, but
+## WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+## General Public License for more details.
 ##
 ## You should have received a copy of the GNU General Public License
-## along with this program.  If not, see <http://www.gnu.org/licenses/>.
+## along with this program.  If not, see
+## <http://www.gnu.org/licenses/>.
 ##
 ## See +LICENSE+ for details.
 
@@ -47,12 +50,6 @@ rescue LoadError
   nil   # just try without then...
 end  
 
-require 'rake'
-require 'dokkit/app'
-require 'dokkit/defaults'
-
 module Dokkit
-
-  # this space intentionally left blank
-
+  VERSION = '0.4.0'
 end 

data/spec/dokkit/application_spec.rb

@@ -0,0 +1,141 @@
+#                                                                          
+# File 'application_spec.rb' created on 08 mag 2008 at 17:26:24.                    
+# See 'dokkit.rb' or +LICENSE+ for licence information.                      
+#                                                                          
+# (c)2006-2008 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors). 
+#                                                                          
+
+$LOAD_PATH.unshift(File.expand_path(File.join(File.dirname(__FILE__),'../../lib')))
+
+require 'rubygems'
+require 'spec'
+require 'dokkit/application'
+require 'spec/spec_helper'
+
+describe Dokkit::Application, ' options behaviour' do
+  include SpecHelper::CaptureOutput, SpecHelper::Logger
+  before(:all) do
+    @initial_dir = Dir.pwd
+    Dir.chdir(File.join(File.dirname(__FILE__), SpecHelper::Path::TEST_DATA))
+  end
+  after(:all) do
+    Dir.chdir(@initial_dir)
+  end
+  before do
+    @logger = logger
+    @dokkit = Dokkit::Application.new(@logger, { :dokkit_dir => 'dokkit', :model_dir => 'models', :default_model => 'model1' })
+  end
+  after do
+    ARGV.clear
+  end
+  it 'should set default model' do
+    @dokkit.default_model.should == 'model1'
+  end
+  it 'should display version number' do
+    ARGV << '--version'
+    capture_stdout do
+      lambda do
+        @dokkit.run
+      end.should raise_error(SystemExit)
+    end.should match(/dokkit, version \d.\d.\d/)
+  end
+  #FIXME: Code duplication here ...
+  it 'should alias --help option with --usage' do
+    ARGV << '--help'
+    @output = capture_stdout do
+      lambda do
+        @dokkit.run
+      end.should raise_error(SystemExit)
+    end
+    @output.should match(/Usage: dokkit/)
+    @output.should match(/Recognized options/)
+  end
+  it 'should display usage information' do
+    ARGV << '--usage'
+    @output = capture_stdout do
+      lambda do
+        @dokkit.run
+      end.should raise_error(SystemExit)
+    end
+    @output.should match(/Usage: dokkit/)
+    @output.should match(/Recognized options/)
+  end
+  it 'should display the list of available models' do
+    ARGV << '--list'
+    @logger.should_receive(:info).with(/model[1-2]/).twice
+    lambda do 
+      @dokkit.run
+    end.should raise_error(SystemExit)
+  end
+  it 'should fail if the number of commandline argument is less than one' do
+    @output = capture_stdout do
+      lambda do 
+        @dokkit.run
+      end.should raise_error(SystemExit)
+    end
+  end
+end
+
+describe Dokkit::Application, ' creating new documentation environment based on builtin model' do
+  include SpecHelper::CaptureOutput, SpecHelper::Logger
+  before(:all) do
+    @initial_dir = Dir.pwd
+    Dir.chdir(File.join(File.dirname(__FILE__), SpecHelper::Path::TEST_DATA))
+  end
+  after(:all) do
+    Dir.chdir(@initial_dir)
+  end
+  before do
+    @logger = logger
+    @dokkit = Dokkit::Application.new(@logger)
+  end
+  after do
+    ARGV.clear
+    FileUtils.rm_rf 'project'
+  end
+  it 'should copy builtin model directory structure on destination dir' do
+    ARGV << 'project'
+    @dokkit.run
+    File.exists?('project/doc/pages/simple.deplate').should be_true
+  end
+  it 'should fail if the destination directory exists' do
+    ARGV << 'project'
+    FileUtils.mkdir 'project'
+    @logger.should_receive(:error).with(/already exists/)
+    @dokkit.run
+  end
+end
+
+describe Dokkit::Application, ' creating new documentation environment based on user models' do
+  include SpecHelper::CaptureOutput, SpecHelper::Logger
+  before(:all) do
+    @initial_dir = Dir.pwd
+    Dir.chdir(File.join(File.dirname(__FILE__), SpecHelper::Path::TEST_DATA))
+  end
+  after(:all) do
+    Dir.chdir(@initial_dir)
+  end
+  before do
+    @logger = logger
+    @dokkit = Dokkit::Application.new(@logger, { :dokkit_dir => 'dokkit', :model_dir => 'models', :default_model => 'model1' })
+  end
+  after do
+    ARGV.clear
+    FileUtils.rm_rf 'project'
+  end
+  it 'should copy model1 directory structure on destination dir' do
+    ARGV << 'project'
+    @dokkit.run
+    File.exists?('project/doc/pages/model1').should be_true
+  end
+  it 'should copy model2 directory structure on destination dir' do
+    ARGV.concat(['--model', 'model2', 'project'])
+    @dokkit.run
+    File.exists?('project/doc/pages/model2').should be_true
+  end
+  it 'should fail if not existent model is specified' do
+    ARGV.concat(['--model', 'notexists', 'project'])
+    @logger.should_receive(:error).with(/not found/)
+    @dokkit.run
+  end
+end

data/spec/dokkit/cache/cache_spec.rb

@@ -0,0 +1,87 @@
+#                                                                          
+# File 'cachemanager_spec.rb' created on 28 gen 2008 at 18:31:31.                    
+# See 'dokkit.rb' or +LICENSE+ for licence information.                      
+#                                                                          
+# (c)2006, 2007 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors). 
+#                                                                          
+# To execute this spec run:                                            
+#                                                                          
+# spec spec/cachemanager_spec.rb                                                  
+#                                                                          
+
+
+$LOAD_PATH.unshift File.expand_path(File.join(File.dirname(__FILE__),'../../../lib'))
+
+require 'rubygems'
+require 'spec'
+require 'dokkit'
+require 'dokkit/cache'
+require 'spec/spec_helper'
+
+describe Dokkit::Cache do
+  include SpecHelper::Path
+
+  before(:all) do
+    @initial_dir = Dir.pwd
+    Dir.chdir(File.join(File.dirname(__FILE__), SpecHelper::Path::TEST_DATA))
+  end
+  after(:all) do
+    Dir.chdir(@initial_dir)
+  end
+
+  describe ' when initialized' do
+    before do
+      mkdir '.cache_test' unless File.exists?('.cache_test')
+      File.open(base_path('.cache_test/deps.rake'), 'w') do |file|
+        file.write YAML::dump({ document_path('document_1') => { 'html' => [document_path('document_1.dep')] } } )
+      end
+      @cache = Dokkit::Cache.new('deps.rake', '.cache_test')
+    end
+    it 'should import the cache file (if exists)' do
+      @cache.deps.should == { document_path('document_1') => { 'html' => [document_path('document_1.dep')] } }
+    end
+    after do
+      @cache.clean
+      rm_rf base_path('.cache_test')
+    end
+  end
+  
+  describe '#add_dependency' do
+    before do
+      @cache = Dokkit::Cache.new('deps.rake', '.cache_test')
+    end  
+    it 'should add dependecies to the given document' do
+      @cache.add_dependency(document_path('document_1'), 'html', 'doc/pages/document_1.dep')
+      @cache.deps.should == { document_path('document_1') => { 'html' => [document_path('document_1.dep')] } }
+    end
+    it 'should not add an existing dependency to the given document' do
+      @cache.add_dependency(document_path('document_1'), 'html', 'doc/pages/document_1.dep')
+      @cache.add_dependency(document_path('document_1'), 'html', 'doc/pages/document_1.dep')
+      @cache.add_dependency(document_path('document_1'), 'html', 'doc/pages/document_2.dep')
+      @cache.deps.should == { document_path('document_1') => { 'html' => ['doc/pages/document_1.dep', 'doc/pages/document_2.dep'] } }      
+    end
+    after do
+      @cache.clean
+      rm_rf '.cache_test'
+      @cache = nil
+    end      
+  end
+  
+  describe '#save' do
+    before do
+      @cache = Dokkit::Cache.new('deps.rake', '.cache_test')
+      @cache.add_dependency(document_path('document_1'), 'html', 'doc/pages/document_1.dep')
+      @cache.add_dependency(document_path('document_1'), 'html', 'doc/pages/document_2.dep')
+      @cache.add_dependency(document_path('document_1'), 'html', 'doc/pages/document_3.dep')
+    end  
+    it 'should save the dependencies to file' do
+      @cache.save
+      File.exists?(base_path('.cache_test/deps.rake')).should be_true
+    end
+    after do
+      @cache.clean
+      rm_rf '.cache_test'
+    end  
+    
+  end
+end