dokkit 0.1.1 → 0.2.0

data/lib/dokkit/hash.rb

@@ -0,0 +1,41 @@
+#                                                                          
+# File 'hash.rb' created on 09 ott 2007 at 15:59:11.                    
+#
+# See 'dokkit.rb' or LICENSE for licence information.                      
+#                                                                          
+# (c)2006, 2007 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors). 
+#                                                                          
+
+class Hash
+  # Set the default values for keyword arguments.
+  # See http://www.lukeredpath.co.uk/2006/7/27/using-ruby-hashes-as-keyword-arguments-with-easy-defaults
+  # for a complete discussion.
+  def with_defaults!(defaults)
+    self.merge!(defaults) { |key, old, new| old.nil? ? new : old }
+  end
+  # Non-desctructive version of Hash#with_defaults method.
+  def with_defaults(defaults)
+    self.merge(defaults) { |key, old, new| old.nil? ? new : old } 
+  end
+  # Hash#recursive_merge merges two arbitrarily deep hashes into a single hash. 
+  # The hash is followed recursively, so that deeply nested hashes that are at 
+  # the same level will be merged when the parent hashes are merged.
+  def recursive_merge!(other_hash)
+    merge!(other_hash) do |key, value, other_value|
+      if(value.class == Hash && other_value.class == Hash)
+        value.recursive_merge other_value
+      elsif(value.class == Array && other_value.class == Array)
+        value.concat(other_value)
+      else
+        store(key, other_value)
+      end
+    end
+  end
+  # Non-destructive version of Hash#recursive_merge method.
+  def recursive_merge(other_hash)
+    dup.recursive_merge!(other_hash)
+  end
+end
+
+
+

data/lib/dokkit/models/Rakefile.tpl

@@ -0,0 +1,9 @@
+#                                                                          
+# File '(>>>FILE<<<)' created on (>>>DATE<<<) at (>>>TIME<<<).                    
+#
+# See 'dokkit.rb' or +LICENSE+ for licence information.                      
+#                                                                          
+# (C) 2006, 2007 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors). 
+#                                                                          
+
+(>>>POINT<<<)

data/lib/dokkit/models/share/builtin.rf

@@ -0,0 +1,28 @@
+require 'rubygems'
+require 'dokkit'
+require 'dokkit/app'
+
+EXCLUDE_FL = /TEMPLATE/
+
+desc "Bootstrap a new documentation project based on #{ENV['PROJECT']} model."
+task :create do
+  rule '' do |t|
+      base_path = File.join(Dokkit.fetch_models[ENV['PROJECT']], 'lib/model')
+      file_to_copy = FileList.new(["#{base_path}/doc/**/*", "#{base_path}/[A-Z]*"]) do |fl|
+        fl.exclude(EXCLUDE_FL).to_a      
+      end
+      copy_model_files base_path, file_to_copy, t.name
+  end
+end
+
+def copy_model_files(base_path, source_fl, dest_dir)
+  puts "Creating model structure on directory '#{dest_dir}'"
+  source_fl.each do |complete_fn|
+    next if File.directory?(complete_fn)
+    complete_fn.scan(/#{base_path}\/(.*)/) do |file_to_copy|
+      dirname = File.join(dest_dir, File.dirname(file_to_copy.to_s))
+      mkdir_p(dirname, :verbose => false) unless File.exists?(dirname)
+      cp complete_fn, dirname, :verbose => true
+    end
+  end
+end

data/lib/dokkit/page.rb

@@ -1,38 +1,107 @@
-# Dokkit page class
-# (c)2006 Andrea Fazzi (and contributors)
+#                                                                          
+# File 'page.rb' created on 09 ott 2007 at 15:56:08.                    
 #
-# See 'dokkit.rb' or LICENSE for licence information.
+# See 'dokkit.rb' or +LICENSE+ for licence information.                      
+#                                                                          
+# (C) 2006, 2007 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors). 
+#                                                                          
 
 require 'yaml'
+require 'dokkit/hash'
+
+class Module
+  def track_methods
+    @methods_in_order = []
+    class << self
+      attr_reader :methods_in_order
+      def method_added( method_name )
+        @methods_in_order << method_name.id2name
+      end
+    end
+  end
+end
 
 module DokkitPage
 
   # The base path for config resolution
   attr_reader :config_path
 
-  def config(fn)
-    @config_files << fn if fn
+  def init(config_page, &blk)
+    self.class.methods_in_order.each do |init_meth|
+      self.send(init_meth, config_page, &blk) if init_meth =~ /init\_/
+    end
+  end
+
+  def load_model_config
+    load_config('model.yaml')
   end
+  
+  def config(basename)
+    basename.each { |fn| @config_files.push "#{fn}#{@config_defext if File.extname(fn).empty?}" } if basename
+  end    
 
   def load_configs
-    @config_files.each do |fn|
-      load_config(fn)
-    end
+    @config_files.each { |fn| load_config(fn) }
     @config
   end
 
   def load_config(fn)
-    if fn = config_fn(fn)
-      raise "Config #{fn} not found" unless File.exists?(fn)
-      Rake.register_dependency(fn)
-      @config.update YAML::load( File.open(fn) )
+    complete_fn = config_fn(fn)
+    if File.exists?(complete_fn) 
+      Rake.register_dependency(complete_fn)
+      result = @config.recursive_merge!( YAML::load( File.open(complete_fn) ) )
+      if result.has_key?('document')
+        if result['document'].has_key?('config')
+          config(result['document'].delete('config'))
+        end
+        if result['document'].has_key?('layout')
+          layout(result['document'].delete('layout'))
+        end
+      end
+      result
+    else
+      nil
     end
   end
 
   def config_fn(fn)
-    File.join(config_path,fn) if fn
+    if File.exists?( complete_fn = fn)
+      return complete_fn
+    elsif File.exists?( complete_fn = File.join(base_path, File.dirname(template_name), fn) )
+      return complete_fn
+    elsif File.exists?( complete_fn = File.join(config_path, fn))
+      return complete_fn
+    elsif File.exists?( complete_fn = File.join(Dokkit.model_config_dir(@config['model']['name']), fn))
+      return complete_fn
+    elsif File.exists?( complete_fn = File.join(Dokkit.model_config_dir(@config['model']['name']), @config['model']['name'] + @config_defext))
+      return complete_fn
+    else
+#      warn "WARNING: Config file #{fn} not found!"
+      return fn
+    end
+  end
+
+  # Find all COMMON.yaml files from given dir up to FS root.
+  def resolve_common_configs(dir, arr = []) # :nodoc:
+    # defer to parent dir first
+    parent = File.expand_path(File.join(dir, '..'))
+    resolve_common_configs(parent,arr) unless parent == dir # at root    
+    fn = File.join(dir,'COMMON.yaml')    
+    arr << fn if (File.exists?(fn) && File.readable?(fn))
+    arr
+  end  
+  
+  def config_hash(key)
+    return @config[key] if @config.has_key?(key)
+    nil
   end
 
+  # Find and evaluate all COMMON.yaml files from page dir up to FS root.
+  def eval_common_configs
+    common_configs = resolve_common_configs(File.expand_path(File.dirname(template_filename)))            
+    common_configs.each { |fn| @config_files.push fn }
+  end # method
+  
 end
 
 module Rote
@@ -40,15 +109,87 @@ module Rote
   class Page
 
     include DokkitPage
+
+    track_methods
     alias page_initialize initialize
 
-    def initialize(template_name, pages_dir = '.', layout_dir = pages_dir, config_dir = pages_dir, &block)
-      @config_files = []
-      @config = {}
-      @config_path = config_dir[STRIP_SLASHES,1]
-      page_initialize(template_name, pages_dir, layout_dir, &block)
-      @config = load_configs
+    def initialize(config_page, &blk)
+      init(config_page, &blk)
+    end
+
+    def page_initialize(config_page)
+      config_page = { :pages_dir => '.', :layout_dir => '.' }.merge(config_page)
+      @template_text = nil
+      @template_name = nil
+      @layout_names = []
+      @content_for_layout = nil
+      @result = nil
+      @layout_defext = config_page[:layout_defext]
+      @layout_path = config_page[:layout_dir][STRIP_SLASHES,1]
+      @layout_text = nil
+      @base_path = config_page[:pages_dir][STRIP_SLASHES,1]
+      
+      @page_filters, @post_filters = [], []
+
+      # read in the template. Layout _may_ get configured later in page code
+      # We only add the pages_dir if it's not already there, because it's
+      # easier to pass the whole relative fn from rake...
+      # template_name always needs with no prefix.
+      tfn = @template_name = config_page[:fn]
+      read_template(tfn)
+      
+      layout(File.basename(tfn, config_page[:template_defext]))
+      
+      # Yield to the (extension mapping) block
+      yield self if block_given?
+      
+      # Eval COMMON.rb's
+      eval_common_rubys
+      
+      # get script filenames, and eval them if found
+      tfn = ruby_filename # nil if no file      
+      instance_eval(File.read(tfn),tfn) if tfn         
+    end
+
+    def init_dokkit_page(config_page, &blk)
+      config_page.with_defaults!(
+       { :pages_dir => '.', 
+         :layout_dir => '.', 
+         :config_dir => '.',
+         :layout_defext => '.html',
+         :config_defext => '.yaml',
+         :template_defext => '.dpl'
+       }
+      )
+     @config_files = []
+     @config = { }
+     @config_path = config_page[:config_dir][STRIP_SLASHES,1]
+     @config_defext = config_page[:config_defext]
+     
+     @template_name = tfn = config_page[:fn] 
+     @base_path = config_page[:pages_dir][STRIP_SLASHES,1]      
+      
+     page_initialize(config_page, &blk)
+           
+     load_model_config
+     eval_common_configs
+     config(File.basename(tfn, config_page[:template_defext]))
+     @config = load_configs
     end
-  end
 
+    private
+        
+    def layout_fn(fn = nil)
+      if File.exists?(complete_fn = File.join(layout_path,fn))
+        return complete_fn
+      elsif File.exists?(complete_fn = File.join(Dokkit.model_layout_dir(@config['model']['name']), fn))
+        return complete_fn
+      elsif File.exists?(complete_fn = File.join(Dokkit.model_layout_dir(@config['model']['name']), @config['model']['name'] + @layout_defext))
+        return complete_fn
+      else
+        raise "Layout file #{fn} not found!"
+      end
+    end
+    
+  end
 end

data/lib/dokkit/render_task_factory.rb

@@ -0,0 +1,91 @@
+#                                                                          
+# File 'render_task_factory.rb' created on 18 Nov 2007 at 16:01:42.                    
+#
+# See 'dokkit.rb' or +LICENSE+ for licence information.                      
+#                                                                          
+# (C) 2006, 2007 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors). 
+#                                                                          
+
+require 'singleton'
+require 'rote/format/html'
+require 'dokkit/filters'
+require 'dokkit/dokkittasks'
+
+module Dokkit
+  class RenderTaskFactory
+    include Singleton
+    def create_render_html(name = :render_html)
+      Rote::DocTask.new(name) do |task|
+        task.output_dir = 'html'
+
+        task.layout_dir = 'doc/layouts'
+        task.config_dir = 'doc/config'
+
+        task.pages.dir = 'doc/pages'
+        task.pages.include('**/*')
+        task.pages.exclude('**/*.yaml')
+
+        task.res.dir = 'doc/res/html'
+        task.res.include('**/*')
+        
+        yield task if block_given?
+        
+        task.ext_mapping(/dpl/, 'html', task.output_dir) do |page|
+          page.extend Rote::Format::HTML
+          page.page_filter Dokkit::Filters::Deplate.new('html-notemplate')
+        end
+      end
+    end
+    def create_render_tex(name = :render_tex)
+      Rote::DocTask.new(name) do |task|
+        task.output_dir = 'tex'
+
+        task.layout_dir = 'doc/layouts'
+        task.layout_defext = '.tex'
+        
+        task.config_dir = 'doc/config'
+
+        task.pages.dir = 'doc/pages'
+        task.pages.include('**/*')
+        task.pages.exclude('**/*.yaml')
+
+        task.res.dir = 'doc/res/tex'
+        task.res.include('**/*')
+        
+        yield task if block_given?
+        
+        task.ext_mapping(/dpl/, 'tex', task.output_dir) do |page|
+          #FIXME: render_tex task must have its own format extension
+          page.extend Rote::Format::HTML
+          page.page_filter Dokkit::Filters::Deplate.new('latex-notemplate')
+        end
+      end
+    end
+    def create_render_text(name = :render_text)
+      Rote::DocTask.new(name) do |task|
+        task.output_dir = 'text'
+
+        task.layout_dir = 'doc/layouts'
+        task.layout_defext = '.text'
+        
+        task.config_dir = 'doc/config'
+
+        task.pages.dir = 'doc/pages'
+        task.pages.include('**/*')
+        task.pages.exclude('**/*.yaml')
+
+        task.res.dir = 'doc/res/text'
+        task.res.include('**/*')
+        
+        yield task if block_given?
+        
+        task.ext_mapping(/dpl/, 'text', task.output_dir) do |page|
+          #FIXME: render_text task must have its own format extension
+          page.extend Rote::Format::HTML
+          page.page_filter Dokkit::Filters::Deplate.new('plain')
+        end
+      end
+    end
+  end
+end
+

data/lib/dokkit.rb

@@ -1,25 +1,38 @@
 # dokkit.rb - main Dokkit module  
-# Copyright (c) 2006 Andrea Fazzi (and contributors)
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy of
-# this software and associated documentation files (the "Software"), to deal in 
-# the Software without restriction, including without limitation the rights to 
-# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies 
-# of the Software, and to permit persons to whom the Software is furnished to do
-# so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in all
-# copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-# SOFTWARE.
-#
-# See Dokkit for full documentation
+
+#####
+## *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 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.
+##
+## See +README+ and http://dokkit.rubyforge.org for general usage information.
+##
+## Copyright (C) 2006, 2007  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 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/>.
+##
+## See +LICENSE+ for details.
 
 # require these before gems, because we want to use them from
 # lib/ , or from normal install, if that's how Dokkit was started.
@@ -42,28 +55,8 @@ end
 require 'rake'
 
 # Master Dokkit version. Manage this from the Rake release support.
-DOKKITVERSION = '0.1.0'
+DOKKITVERSION = '0.2.0'
 
-#####
-## *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, layout, and optionally plain-text formatting
-## (HTML-only at present) 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 of Alca Coop (http://alca.le.it/)
-## and it is a fairly flexible tool. Dokkit can handle the internal documentation of
-## your software house.
-##
-## 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.
-##
-## See +README+ for general usage information.
-##
-## Dokkit is (c)2006 Andrea Fazzi (and contributors). See +LICENSE+ for details.
 module Dokkit
 
   # this space intentionally left blank

data/tests/data/output/simple_document/README

@@ -0,0 +1,57 @@
+This is 'simple_document' a simple document model included in the core
+distribution of dokkit. Check http://rubyforge.org/dokkit/ for other
+models. 
+
+To modify this document simply edit 'doc/pages/simple_document.dpl'. To get further
+information about the wiki syntax to be used please check http://deplate.sf.net/
+
+To render this document in html, type:
+
+  dokkit render_html
+
+from any subdirectory contained in the top-level directory (this one).
+  
+To render this document in TeX, type:
+
+  dokkit render_tex
+
+In either case, you should get the output in a (created) 'output'
+directory:
+
+  in 'output/html' you get html output
+  in 'output/tex' you get tex output
+
+  ... and so on...
+
+Once you have rendered the document, running the command again will appear
+to do nothing, because only changed resources are re-rendered. To
+clean the output and start over:
+
+  dokkit clobber
+
+Alternatively, modify the page or resource files, and rerun 
+
+  dokkit render_html
+
+  or
+
+  dokkit render_tex
+
+to transform only the modified resource.
+
+* WHAT'S NEXT?
+
+ - See what else you can do by typing:
+
+    dokkit --tasks
+
+ - Modify the configuration of the document by editing
+   'doc/config/simple_document.yaml'
+
+ - Create a new document by typing: 
+     
+    dokkit create_new_page new_document
+
+For further information about dokkit see http://dokkit.rubyforge.org/
+
+

data/tests/data/output/simple_document/Rakefile

@@ -0,0 +1,7 @@
+# Rakefile for simple_document project model
+
+require 'dokkit'
+require 'dokkit/app'
+import File.join(Dokkit.projects_dir,"simple_document","lib/rakefile.rf")
+
+

data/tests/data/output/simple_document/doc/config/simple_document.yaml

@@ -0,0 +1,5 @@
+title: A Simple Document
+author: John Doe
+
+
+

data/tests/data/output/simple_document/doc/pages/simple_document.dpl

@@ -0,0 +1,12 @@
+* Abstract
+From a document of Jim{cite: author:jim}
+
+* Introduction
+
+* Main section
+
+** Subsection One
+** Subsection Two
+
+* Conclusions
+

data/{lib/dokkit/projects/website → tests/data/output/website_project}/Rakefile

@@ -38,7 +38,8 @@ include Dokkit
 ws = Rote::DocTask.new(:doc) do |site| 
   site.output_dir = 'html'
   site.layout_dir = 'doc/layouts'
-  
+  site.config_dir = 'doc/config'
+
   site.pages.dir = 'doc/pages'
   site.pages.include('**/*')   
    

data/tests/data/projects/simple-document/README

@@ -0,0 +1,57 @@
+This is 'simple_document' a simple document model included in the core
+distribution of dokkit. Check http://rubyforge.org/dokkit/ for other
+models. 
+
+To modify this document simply edit 'doc/pages/simple_document.dpl'. To get further
+information about the wiki syntax to be used please check http://deplate.sf.net/
+
+To render this document in html, type:
+
+  dokkit render_html
+
+from any subdirectory contained in the top-level directory (this one).
+  
+To render this document in TeX, type:
+
+  dokkit render_tex
+
+In either case, you should get the output in a (created) 'output'
+directory:
+
+  in 'output/html' you get html output
+  in 'output/tex' you get tex output
+
+  ... and so on...
+
+Once you have rendered the document, running the command again will appear
+to do nothing, because only changed resources are re-rendered. To
+clean the output and start over:
+
+  dokkit clobber
+
+Alternatively, modify the page or resource files, and rerun 
+
+  dokkit render_html
+
+  or
+
+  dokkit render_tex
+
+to transform only the modified resource.
+
+* WHAT'S NEXT?
+
+ - See what else you can do by typing:
+
+    dokkit --tasks
+
+ - Modify the configuration of the document by editing
+   'doc/config/simple_document.yaml'
+
+ - Create a new document by typing: 
+     
+    dokkit create_new_page new_document
+
+For further information about dokkit see http://dokkit.rubyforge.org/
+
+

data/tests/data/projects/simple-document/Rakefile

@@ -0,0 +1,22 @@
+#                                                                          
+# File 'Rakefile' created on 09 ott 2007 at 16:06:57.                    
+#
+# See 'dokkit.rb' or +LICENSE+ for licence information.                      
+#                                                                          
+# (C) 2006, 2007 Andrea Fazzi <andrea.fazzi@alca.le.it> (and contributors). 
+#                                                                          
+# Rakefile for simpledocument project model
+
+require 'dokkit'
+require 'dokkit/app'
+require 'dokkit/render_task_factory'
+
+
+factory = Dokkit::RenderTaskFactory.instance
+
+factory.create_render_html
+factory.create_render_tex
+
+task :default => [:render_html]
+
+

data/tests/data/projects/simple-document/doc/config/author.yaml

@@ -0,0 +1,4 @@
+document:
+  author:
+    email: john.doe@organization.org
+