dokkit 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c)2006 Andrea Fazzi (and contributors). All rights reserved.
+
+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.
+

data/Rakefile

@@ -0,0 +1,62 @@
+# Standard Rakefile for custom Dokkit build
+#
+# 
+
+begin 
+  require 'rubygems'
+rescue LoadError
+  nil # optional
+end
+
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+
+CLOBBER.include('html')
+CLOBBER.include('tex')
+
+Rake::RDocTask.new do |rd|
+  rd.main = "README"
+  rd.rdoc_files.include("README", "lib/**/*.rb", "tests/*.rb")
+  rd.rdoc_dir = "apidoc"
+  rd.options.push('-d').push('-F')
+end	
+
+desc "Run basic tests"
+Rake::TestTask.new("test_units") { |t|
+  t.pattern = 'tests/ts_*.rb'
+  t.verbose = true
+  #t.warning = true
+}
+
+spec = Gem::Specification.new do |s|
+  s.platform = Gem::Platform::RUBY
+  s.summary = "Ruby Documentation ToolKit."
+  s.name = 'dokkit'
+  s.version = '0.1.0'
+
+  s.add_dependency('deplate', '>= 0.8')
+  s.add_dependency('rote', '>= 0.3.2.2')
+  s.add_dependency('rake')
+  s.add_dependency('syntax')
+
+  s.has_rdoc = true
+  s.test_file = 'tests/gem_tests.rb'
+
+  s.require_path = 'lib'
+  s.autorequire = 'dokkit'
+  s.bindir = 'bin'
+  s.executables << 'dokkit'
+  s.extra_rdoc_files << 'README'	
+  s.files = FileList['lib/**/*', 'bin/*', '[A-Z]*', 'tests/*', 'tests/**/**'].exclude(/alca/).to_a
+  s.description = <<-EOF
+    Dokkit is a documentation toolkit based on Rote.
+  EOF
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_zip = true
+  pkg.need_tar = true
+end

data/bin/dokkit

@@ -0,0 +1,53 @@
+#
+# Commandline launcher for Dokkit, (c)2006 Andrea Fazzi (and contributors)
+#
+# Get set up with library paths, however we're installed.
+
+def croak
+	puts "Cannot locate Dokkit libraries - Do you need to set $DOKKIT_LIB ?"
+	exit(1)
+end
+
+begin 
+	require 'rubygems'
+rescue LoadError
+	# just ignore, don't use gems
+end
+
+fail = false
+
+dokkit_lib = nil
+
+begin
+	require 'dokkit'
+	require 'dokkit/app'
+		
+	# find this later
+	dokkit_lib = nil
+rescue LoadError
+	unless fail || !(dokkit_lib = ENV['DOKKIT_LIB'])	
+		$: << dokkit_lib		
+		# at least we can know this now...
+		builtin = File.join(dokkit_lib,'dokkit/builtin.rake')
+		fail = true		# next time.
+		retry
+	else
+		croak
+	end 
+end
+
+# If we're loaded via RubyGems or some such we need to locate
+# the builtin rakefile.
+unless dokkit_lib
+  $:.each { |it|
+    if File.exists?(File.join(it,'dokkit/builtin.rake'))
+      dokkit_lib = it
+      break
+    end
+  }  
+end
+
+croak unless dokkit_lib
+
+Dokkit::Application.new(dokkit_lib).run
+

data/lib/dokkit/app.rb

@@ -0,0 +1,305 @@
+# Dokkit application class
+# (c)2006 Andrea Fazzi (and contributors)
+#
+# See 'dokkit.rb' or LICENSE for licence information.
+
+require 'optparse'
+require 'rake'
+
+DEFAULT_PROJECT_MODEL = "tech_report"
+
+module Rake
+
+  class Application
+
+    def do_option(opt, value)
+      case opt
+      when '--directory'
+	Dir.chdir( File.expand_path(value) )
+	options.directory = true
+      when '--dry-run'
+	verbose(true)
+	nowrite(true)
+	options.dryrun = true
+	options.trace = true
+      when '--help'
+	help
+	exit
+      when '--libdir'
+	$:.push(value)
+      when '--nosearch'
+	options.nosearch = true
+      when '--prereqs'
+	options.show_prereqs = true
+      when '--quiet'
+	verbose(false)
+      when '--rakefile'
+	RAKEFILES.clear
+	RAKEFILES << value
+      when '--rakelibdir'
+	options.rakelib = value.split(':')
+      when '--require'
+        begin
+          require value
+        rescue LoadError => ex
+          begin
+            rake_require value
+          rescue LoadError => ex2
+            raise ex
+          end
+        end
+      when '--silent'
+	verbose(false)
+	options.silent = true
+      when '--tasks'
+	options.show_tasks = true
+	options.show_task_pattern = Regexp.new(value || '.')
+      when '--trace'
+	options.trace = true
+	verbose(true)
+      when '--usage'
+	usage
+	exit
+      when '--verbose'
+	verbose(true)
+      when '--version'
+	puts "rake, version #{RAKEVERSION}"
+	exit
+      when '--classic-namespace'
+	require 'rake/classic_namespace'
+	options.classic_namespace = true
+      else
+	fail "Unknown option: #{opt}"
+      end
+    end
+
+    def handle_options
+      options.rakelib ||= 'rakelib'
+      options.each { |opt, value| do_option(opt, value) }
+    end
+  
+    def display_tasks_and_comments
+      displayable_tasks = Rake::Task.tasks.select { |t|
+	t.comment && t.name =~ options.show_task_pattern
+      }
+      width = displayable_tasks.collect { |t|
+	t.name.length
+      }.max
+      displayable_tasks.each do |t|
+	printf "dokkit %-#{width}s  # %s\n", t.name, t.comment
+      end
+    end
+
+    # Search for a Rakefile
+    def search_for_rakefile
+      initial_dir = here = Dir.pwd
+        while ! have_rakefile
+	  Dir.chdir("..")
+	  if Dir.pwd == here
+            Dir.chdir(initial_dir)
+	    return false
+	  end
+	  here = Dir.pwd
+        end
+      return true
+    end
+
+  end
+
+end
+
+module Dokkit
+
+  # Command-line launcher for Dokkit.
+  class Application
+
+    attr_accessor :dokkit_lib
+    attr_accessor :debug
+    attr_accessor :tasks
+    attr_accessor :trace
+    attr_accessor :usage
+    attr_accessor :version
+    attr_accessor :rake
+    attr_accessor :rakefile
+    attr_accessor :rakeopts
+    attr_accessor :rake_env
+    attr_accessor :list_projects
+
+    @@project_dirs = nil
+
+    # Create a new Application instance, processing command-line arguments,
+    # optionally passing +self+ to the supplied block for further 
+    # configuration.
+
+    def initialize(dokkit_lib) # :yield: self if block_given?
+      # init vars
+      @@project_dirs = ($:.collect { |dir| File.join(dir,"dokkit/projects")}).concat(Array["~/.dokkit/projects"])
+
+      @dokkit_lib = dokkit_lib
+      @debug = false
+      @tasks = false
+      @trace = false
+      @usage = false
+      @version = false
+      @list_projects = false
+      @directory = false
+      @rf = false
+      @rakefile = "#{dokkit_lib}/dokkit/builtin.rake"
+      raise "Missing builtin.rake (expected at '#{@rakefile}')!" unless File.exists?(@rakefile)
+      
+      @rakeopts = ENV['RAKE_OPTS'] || ''
+      @rake_env = "PROJECT=#{@project}"
+
+      ENV['PROJECT'] = @project = DEFAULT_PROJECT_MODEL
+      
+      @rake = Rake::Application.new
+
+      process_args
+      
+      yield self if block_given?
+    end
+    
+    # Gets the list of the directory to search into for project models
+    def Application.get_project_dirs
+      @@project_dirs
+    end 
+
+    # Run the application with the current options.
+    def run
+
+      @rake.do_option("--libdir",dokkit_lib)
+
+      if @version
+        print "dokkit, version #{DOKKITVERSION}\n"
+
+      elsif @tasks
+        if @rake.search_for_rakefile
+           @rake.do_option("--rakelibdir","#{dokkit_lib}/dokkit/")
+           @rake.do_option("--tasks",nil)
+           @rake.run
+        else
+           @rake.do_option("--tasks",nil)
+           @rake.do_option("--rakefile","#{rakefile}")
+           @rake.run
+        end
+      elsif @list_projects
+          show_all_projects
+      elsif @usage
+        show_usage()
+      else
+        if @trace
+          @rake.do_option("--trace",nil)
+        elsif @debug
+          @rake.do_option("--verbose",nil)
+        elsif @rf
+          @rake.do_option("--rakefile",@rf)
+        elsif @directory
+          @rake.do_option("--directory",@directory)
+        elsif @project
+          ENV['PROJECT'] = @project
+        end
+
+        if @rake.search_for_rakefile
+           @rake.do_option("--rakelibdir","#{dokkit_lib}/dokkit/")
+        else
+           @rake.do_option("--rakefile","#{rakefile}")
+        end
+
+        @rake.run
+      
+      end
+    end
+    
+    private
+
+    # Process commandline
+    def process_args
+      GetoptLong.new(
+        [ "--verbose", "-v", GetoptLong::NO_ARGUMENT ],
+        [ "--tasks",   "-T", GetoptLong::NO_ARGUMENT ],
+        [ "--trace",   "-t", GetoptLong::NO_ARGUMENT ],
+        [ "--usage",   "-u", GetoptLong::NO_ARGUMENT ],
+	[ "--project", "-P", GetoptLong::REQUIRED_ARGUMENT],
+	[ "--rakefile","-f", GetoptLong::REQUIRED_ARGUMENT],
+	[ "--directory","-D", GetoptLong::REQUIRED_ARGUMENT],
+	[ "--list",    "-l", GetoptLong::NO_ARGUMENT ],
+        [ "--help",    "-h", GetoptLong::NO_ARGUMENT ],
+        [ "--version", "-V", GetoptLong::NO_ARGUMENT ]
+      ).each { |opt,arg|
+        @debug = true if opt == '--verbose'
+        @trace = true if opt == '--trace'
+        @tasks = true if opt == '--tasks'
+	@project = arg if opt == '--project'
+        @rf = arg if opt == '--rakefile'
+	@directory = arg if opt == '--directory'
+        @list_projects = true if opt == '--list'
+        @usage = true if opt == '--usage' || opt == '--help'
+        @version = true if opt == '--version'
+      }
+    end
+    
+    # Show all the projects present in the distro default dir $DOKKIT_LIB/dokkit/projects/
+    # and into the user dir $HOME/.dokkit/projects
+    def show_all_projects
+      puts "Searching in #{dokkit_lib}.."
+      puts "Available project models are:"
+      Dir["#{dokkit_lib}/dokkit/projects/**/Rakefile"].concat(Dir["#{File.expand_path("~/.dokkit/projects/**/Rakefile")}"]).each do |project| 
+        puts File.dirname(project).scan(/projects\/\w+\/*\w+/).to_s.gsub!(/projects\//,"")
+      end
+    end
+
+    # Display help text
+    def show_usage
+      print <<-EOM
+Usage: dokkit [options] [task1] .. [taskN]
+
+Where [taskN] is a valid task or target name for the current project. 
+Dokkit generates targets for each page source, and also defines a number
+of top-level tasks for various things. Use the '--tasks' option to get
+a list of valid tasks.
+
+Recognised options are:
+
+  --directory=DIR -D
+	Change to directory DIR before reading the rakefiles or doing anything else.
+
+  --rakefile=FILE -f
+	Use FILE as a Rakefile.
+
+  --list      -l
+	Display the list of model projects available.
+
+  --help      -h
+	Synonym for --usage
+
+  --project=PROJECT   -P
+	Sets the model project to create. Use --list for the full list of available projects.
+
+  --tasks     -T
+	Display a list of tasks in this project.
+
+  --trace     -t		
+	Enables trace-level output (debugging).
+
+  --usage     -u
+	Display this help message and quit.
+
+  --verbose   -v
+	Enable verbose output.
+
+  --version   -V
+	Display Dokkit's version and quit
+
+In addition to the standard doc_XXX tasks and those provided by any
+local configuration, the following 'special' tasks are recognised:
+
+  create <project>   Create a blank project from the built-in template using the #{DEFAULT_PROJECT_MODEL} project model.
+
+In non-standard environments, it may be necessary to set the DOKKIT_LIB 
+variable to point to the location of Dokkit's libraries.
+  
+EOM
+    end
+        
+  end # Application
+end # Dokkit

data/lib/dokkit/builtin.rake

@@ -0,0 +1,55 @@
+# Built-in Dokkit rakefile
+#
+# This is effectively a copy of the template rakefile, 
+# but with extra tasks for the command-line wrapper.
+#
+# (c)2006 Andrea Fazzi (and contributors)
+# 
+begin 
+  require 'rubygems'
+rescue LoadError
+  nil # optional
+end
+require 'rake'
+require 'rake/clean'
+require 'dokkit'
+
+# Import tasks for current project
+
+#################### CREATE NEW PROJECT FROM TEMPLATE ###############
+#
+# This works in a slightly odd way. The 'create' task simply sets up
+# a rule that catches anything. This rule will then be triggered by
+# the task that follows on the command-line, and taken as the 
+# target directory name.
+# 
+# So instead of 'dokkit create NAME=foo' we have 'dokkit create foo'
+#
+# Note that this does preclude having other tasks on the same 
+# invocation (after the create at least) but does also allow
+# multiple projects to be created at once. 
+#
+# Also need a way to display error message if the rule isn't 
+# invoked at least once...
+#     /(((\w*\/)*)(\w*))\/{2}(((\w*\/)*)(\w*))/.match(t.name)
+
+desc "Bootstrap a new documentation project"
+task :create do
+  rule '' do |t|
+    fail "#{t.name} already exists" if File.exists?(t.name)
+	
+    src = ENV['PROJECT']
+    src_dir = Dokkit::Application.get_project_dirs.detect { |it| File.exists?(File.join(File.expand_path(it),src)) }
+
+    fail "Cannot locate project template #{src}!\n" unless src_dir
+    
+    cp_r File.join(File.expand_path(src_dir), src), t.name
+  end
+end
+
+#src = ENV['PROJECT']
+#src_dir = Dokkit::Application.get_project_dirs.detect { |it| File.exists?(File.join(File.expand_path(it),src)) }
+
+#import "#{File.join(File.join(src_dir,src),'Rakefile')}" if File.exists?(File.join(File.join(src_dir,src),'Rakefile'))
+#import File.join(File.dirname(__FILE__),('/projects/tech_report/Rakefile'))
+

data/lib/dokkit/deplate/fmt/html-notemplate.rb

@@ -0,0 +1,21 @@
+# latex-notemplate.rb
+# @Author:      Andrea Fazzi (andrea.fazzi AT alca.le.it)
+# @Website:     http://alca.le.it/
+# @License:     GPL (see http://www.gnu.org/licenses/gpl.txt)
+# @Created:     04-Dic-2006.
+# @Last Change: 04-Dic-2006.
+# @Revision:    0.1
+
+require 'deplate/fmt/html'
+
+class Deplate::Formatter::HTMLNoTemplate < Deplate::Formatter::HTML
+  self.myname = "html-notemplate"
+  self.rx     = /html?(-notemplate)?/i
+
+
+  def prepare
+  end
+
+  def add_package(pkg, *options)
+  end
+end

data/lib/dokkit/deplate/fmt/latex-notemplate.rb

@@ -0,0 +1,22 @@
+# latex-notemplate.rb
+# @Author:      Luca Greco (luca.greco AT alca.le.it)
+# @Website:     http://alca.le.it/
+# @License:     GPL (see http://www.gnu.org/licenses/gpl.txt)
+# @Created:     16-Oct-2006.
+# @Last Change: 16-Oct-2006.
+# @Revision:    0.1
+
+require 'deplate/fmt/latex'
+
+class Deplate::Formatter::LatexNoTemplate < Deplate::Formatter::LaTeX
+  self.myname = "latex-notemplate"
+  self.rx     = /(la)?tex(-notemplate)?/i
+
+
+  def prepare
+  end
+
+  def add_package(pkg, *options)
+  end
+end
+

data/lib/dokkit/dokkittasks.rb

@@ -0,0 +1,69 @@
+#--
+# Rake tasklib for Dokkit
+# (c)2006 Andrea Fazzi (and contributors)
+#
+# See 'dokkit.rb' or LICENSE for licence information.
+#++
+
+require 'rote/rotetasks.rb'
+
+module Rote
+
+  class DocTask
+
+    # Base directories used by the task.
+    attr_accessor :config_dir
+
+    # define a task for each page, and 'all pages' task
+    def define_page_tasks
+      pages_fl = pages.to_filelist    
+
+      gen_files = pages_fl.select { |fn| not File.directory?(fn) }.map do |fn|
+        tfn, blk = target_fn(/^#{pages.dir}/, fn) 
+                 
+        desc "#{fn} => #{tfn}" #if show_file_tasks?
+        file tfn => [fn] do
+          dn = File.dirname(tfn)
+          mkdir_p dn unless File.exists?(dn)
+          puts "tr #{fn} => #{tfn}"
+          begin
+            File.open(tfn, 'w+') do |f|
+              # new page, run extension block, render out, throw away
+              f << Page.new(fn,pages.dir,layout_dir,config_dir,&blk).render
+            end
+          rescue => e
+            # Oops... Unlink file and dump backtrace
+            File.unlink(tfn)
+            bt = e.backtrace
+            end_idx = bt.each_with_index do |entry, idx|
+              break idx if entry =~ /^#{File.dirname(__FILE__)}/
+            end
+            puts bt[0...end_idx]
+            raise
+          end
+        end
+        
+        # Each page depends properly on source and common - thx again
+        # Jonathan :)
+        src_rb = Page::page_ruby_filename(fn)
+        if File.exists?(src_rb)
+          file tfn => [src_rb]
+        end
+        
+        common_rbs = Page::resolve_common_rubys(File.dirname(fn))
+        file tfn => common_rbs unless common_rbs.empty?
+        
+        tfn
+      end
+      
+      desc "Render new/changed documentation pages"
+      task "#{name}_pages" => gen_files
+      task "clobber_#{name}_pages" do
+        gen_files.each do |f|
+          rm_f f
+        end
+      end    
+    end
+
+  end
+end

data/lib/dokkit/filters/deplate.rb

@@ -0,0 +1,37 @@
+#--
+# Dokkit filter for Deplate
+# (c)2006 Andrea Fazzi (and contributors)
+#
+# See 'dokkit.rb' or LICENSE for licence information.
+
+require 'deplate/converter'
+require 'deplate/core'
+require 'rote/filters/base'
+require 'dokkit/deplate/fmt/latex-notemplate'
+require 'dokkit/deplate/fmt/html-notemplate'
+
+module Dokkit
+  module Filters
+    #####
+    ## Page filter that converts emacs-wiki formatting to tex using 
+    ## deplate. 
+    ##
+    class Deplate < Rote::Filters::TextFilter
+    
+      # Create a new filter instance. If a block is defined returns a Deplate::Converter instance.
+      # You can supply options directly to the instance. See deplate docs for a full list
+      # of options.
+      def initialize(formatter)
+        super()
+        ::Deplate::Core.declare_formatter(::Deplate::Formatter::LatexNoTemplate,'latex-notemplate')
+        ::Deplate::Core.declare_formatter(::Deplate::Formatter::HTMLNoTemplate,'html-notemplate')
+        @deplate = ::Deplate::Converter.new(formatter) { |instance| yield(instance) if block_given? }
+      end      
+      
+      def handler(text,page)
+        @deplate.convert_string(text) 
+      end      
+    end    
+  end
+end
+    

data/lib/dokkit/filters.rb

@@ -0,0 +1,26 @@
+#--
+# Require all filters
+# (c)2005, 2006 Ross Bamford (and contributors)
+#
+# See 'rote.rb' or LICENSE for licence information.
+# $Id: filters.rb 156 2006-01-05 01:13:43 +0000 (Thu, 05 Jan 2006) roscopeco $
+#++
+
+# Everyone requires this, we need to get it loaded first.
+require 'rote/filters/base'
+
+# This now requires conservatively, ignoring any filters that
+# throw a LoadError. This allows a simple 'require rote/filters' to
+# be used to load all filters _for which dependencies are
+# available_.
+Dir[File.join(File.dirname(__FILE__), 'filters/*.rb')].each do |fn|
+  begin
+    require fn unless fn =~ /[\\\/]base.rb$/
+  rescue LoadError
+
+    # ignore, different filters require different library
+    # support.
+
+  end
+end
+