docjs 0.1.2 → 0.1.3

data/README.md

@@ -1,12 +1,13 @@
 Doc.js
 ======
-Just a note: After total dataloss i have to rewrite the Readme's and Test's, so 
-please be patient.
+Bad news first: **You still have to write documentation**
+
+Good news: **It will look awesome!!**
 
 
 Supported Ruby-Version
 ======================
-Currently **only > 1.9** is supported. I am working on 1.8.x, though this is not 
+Currently **only ruby > 1.9** is supported. I am working on supporting > 1.8.7, though this is not 
 my target platform.
 
 
@@ -77,6 +78,7 @@ You will find the docs in the output-directory you have specified in your
 config-file.
 
 
-License
-=======
+Legal Notice
+============
 docjs is released under MIT-License. See LICENSE.md for more information.
+The used icons, are part of the legendary famfamfam-silk-iconset. (http://www.famfamfam.com/lab/icons/silk/)

data/bin/docjs

@@ -47,7 +47,7 @@ class DocJs < Thor
                   { :type => :string, :aliases => '-n', :default => "MyAppName" },
                   
               :logfile =>
-                  { :type => :string, :aliases => '-lf', :default => 'docjs.log' },
+                  { :type => :string, :aliases => '-lf' },
                   
               :loglevel =>
                   { :type => :string, :aliases => '-ll', :default => 'info' }
@@ -60,6 +60,7 @@ class DocJs < Thor
       setup_application configs
       
       # load application specific files
+      Logger.debug "Loading application-templates: #{Configs.templates + '/application.rb'}"
       require Configs.templates + '/application.rb'
       
       # Config Thor settings
@@ -85,16 +86,36 @@ class DocJs < Thor
     
     
     
-  desc "tokens", "Lists all supported tokens"
-  def tokens
-    say "Supported tokens:"
-    say Token::Handler.handlers.map{|k,v| "  @#{k}" }.sort.join "\n"    
+  desc "tokens TEMPLATE_PATH?", "Lists all supported tokens\nNeeds your TEMPLATE_PATH to include your own custom tokens. If TEMPLATE_PATH is ommitted, only the default-tokens will be shown"
+  set_options :details => 
+                 { :type => :boolean, :default => false }
+  def tokens(template_path = nil)
+  
+    unless template_path.nil?
+      require File.absolute_path(template_path) + '/application.rb'
+    else
+      require Configs.root + 'templates/application.rb'
+    end
+  
+    say "Supported tokens:\n\n"
+    if options.details?
+      table = [%w(TOKEN AREA TEMPLATE DESCRIPTION)] + Token::Handler.handlers.map{|k,v| [":#{k}",v.area, v.template, v.description] }.sort
+    else
+      table = Token::Handler.handlers.map{|k,v| [":#{k}","# #{v.description}"] }.sort
+    end
+    print_table table, :ident => 2, :colwidth => 20
   end
   
   
   
-  desc "tasks", "Lists all registered render-tasks"
-  def tasks
+  desc "tasks TEMPLATE_PATH?", "Lists all registered render-tasks\nNeeds your TEMPLATE_PATH to include your own custom tokens. If TEMPLATE_PATH is ommitted, only the default-tokens will be shown"
+  def tasks(template_path = nil)
+    unless template_path.nil?
+      require File.absolute_path(template_path) + '/application.rb'
+    else
+      require Configs.root + 'templates/application.rb'
+    end
+    
     say "Registered render-tasks:"
     
     task_table = Processor.render_tasks.map{|k,v| [":#{k}","# #{v.description}"] }.sort
@@ -104,7 +125,6 @@ class DocJs < Thor
   
   
   
-  # @todo implement!
   desc "scaffold OUTPUT_DIR", "You can use scaffolding to get the templates and some basic ruby-files, that you will need to create your own templates"
   set_options :logfile =>
                   { :type => :string, :aliases => '-lf', :default => 'jsdoc.log' },
@@ -177,6 +197,11 @@ class DocJs < Thor
       build['templates'] = ask ">"
     end
     
+    if not build['output']
+      say "\nWhere do you wan't your documentation generated to? Please enter a path", :bold
+      build['output'] = ask ">"
+    end
+    
     if not build['loglevel']
       say "\nPlease specify the loglevel of your output: (error|warn|info|debug)", :bold
       

data/bin/docjs.rb

@@ -0,0 +1,239 @@
+#!/usr/bin/ruby1.9
+# We need pathname to make it work with sym-links
+require 'pathname' 
+require Pathname.new(__FILE__).realpath + '../../lib/boot'
+
+# @todo The general flow of information should be documented here
+# 
+# --String--> [Parser] --Commentstream--> [CodeObjectFactory] --Objectstream--> [Registry]
+#
+# Parser
+# ------
+# Turns the incoming stream of characters (string) into a stream of 
+# {Parser::Comment comments}. Those comments contain the parsed doclines, which
+# are simply all lines found in the comment and all tokenlines. 
+
+# configure approot
+Configs.set :root  => Pathname.new(__FILE__).realpath + '../..'
+
+# Pipeline:
+#   1. load options from shell and specified YAML-file (if any)
+#   2. load files
+#   3. parse files
+#   4. turn into objects and save to dom
+#   5. render templates
+#
+# @note options declared in a build.yml will override command-line ones
+# @todo command line option to copy all templates to specified directory like
+#   jsdoc dump_templates ../templates/original
+class DocJs < Thor
+    
+  include Thor::Actions
+    
+  desc "CONFIG_FILE", "Starts documentation process"
+  set_options :files =>
+                  { :type => :array,  :aliases => '-f', :default => [], :required => true },
+               
+              :docs =>
+                  { :type => :array,  :aliases => '-d', :default => ['README.md'], :required => true },
+  
+              :output =>
+                  { :type => :string, :aliases => '-o', :default => 'out' },
+                  
+              :templates =>
+                  { :type => :string, :aliases => '-t', :default => Configs.root + 'templates' },
+                  
+              :appname =>
+                  { :type => :string, :aliases => '-n', :default => "MyAppName" },
+                  
+              :logfile =>
+                  { :type => :string, :aliases => '-lf' },
+                  
+              :loglevel =>
+                  { :type => :string, :aliases => '-ll', :default => 'info' }
+  
+  def docjs(config_file = nil)
+    # @see Thor#merge_options
+    configs = config_file ? merge_options(options, config_file) : options
+    
+    begin
+      setup_application configs
+      
+      # load application specific files
+      Logger.debug "Loading application-templates: #{Configs.templates + '/application.rb'}"
+      require Configs.templates + '/application.rb'
+      
+      # Config Thor settings
+      DocJs.source_root(Configs.templates)
+      self.destination_root = Configs.output
+      
+      Processor.prepare_documents
+      # let's check our Documents tree
+      Dom.docs.print_tree
+      
+      # the configs are now available through our Configs-module      
+      Processor.process_and_render
+        
+      Logger.info "Copying template resources to output"
+      directory 'resources/img', './img' # copy resources
+      directory 'resources/css', './css'
+      directory 'resources/js', './js'
+            
+    rescue Exception => error
+      Logger.error error.message + "\n" + error.backtrace.map{|l| "  #{l}" }.join("\n")
+    end    
+  end  
+    
+    
+    
+  desc "tokens TEMPLATE_PATH?", "Lists all supported tokens\nNeeds your TEMPLATE_PATH to include your own custom tokens. If TEMPLATE_PATH is ommitted, only the default-tokens will be shown"
+  set_options :details => 
+                 { :type => :boolean, :default => false }
+  def tokens(template_path = nil)
+  
+    unless template_path.nil?
+      require File.absolute_path(template_path) + '/application.rb'
+    else
+      require Configs.root + 'templates/application.rb'
+    end
+  
+    say "Supported tokens:\n\n"
+    if options.details?
+      table = [%w(TOKEN AREA TEMPLATE DESCRIPTION)] + Token::Handler.handlers.map{|k,v| [":#{k}",v.area, v.template, v.description] }.sort
+    else
+      table = Token::Handler.handlers.map{|k,v| [":#{k}","# #{v.description}"] }.sort
+    end
+    print_table table, :ident => 2, :colwidth => 20
+  end
+  
+  
+  
+  desc "tasks TEMPLATE_PATH?", "Lists all registered render-tasks\nNeeds your TEMPLATE_PATH to include your own custom tokens. If TEMPLATE_PATH is ommitted, only the default-tokens will be shown"
+  def tasks(template_path = nil)
+    unless template_path.nil?
+      require File.absolute_path(template_path) + '/application.rb'
+    else
+      require Configs.root + 'templates/application.rb'
+    end
+    
+    say "Registered render-tasks:"
+    
+    task_table = Processor.render_tasks.map{|k,v| [":#{k}","# #{v.description}"] }.sort
+    
+    print_table task_table, :ident => 2, :colwidth => 20    
+  end  
+  
+  
+  
+  desc "scaffold OUTPUT_DIR", "You can use scaffolding to get the templates and some basic ruby-files, that you will need to create your own templates"
+  set_options :logfile =>
+                  { :type => :string, :aliases => '-lf', :default => 'jsdoc.log' },
+                  
+              :loglevel =>
+                  { :type => :string, :aliases => '-ll', :default => 'info' }
+  def scaffold(output_dir)
+      
+    setup_application options.merge({
+      :output => output_dir,
+      :templates => output_dir
+    })
+    
+    # Setup Thor paths
+    DocJs.source_root(Configs.root)
+    self.destination_root = Configs.output
+
+    yes_no = "(y|n)"
+    
+    Logger.info "We need some information from you, to customize the scaffolding process to your needs."    
+    if yes? "Do you wan't to generate a build.yml? #{yes_no}"
+      configure(Configs.wdir + '/build.yml', {
+        'templates' => output_dir,
+        'output'    => 'docs',
+        'logfile'   => 'logfile.log',
+        'loglevel'  => 'info'
+      })
+    end
+        
+    # Work with the answers    
+    Logger.info "Copying the template files to #{Configs.templates}"
+    directory 'templates', Configs.templates    # copy templates and resources
+        
+    Logger.info "Copying the included *.rb files to #{Configs.includes}"    
+  end
+  
+  desc "configure [NEW_CONFIGFILE]", "Helps you creating your build.yml to start off with doc.js"
+  def configure(output_file = "build.yml", preconfigured = {})
+    
+    build = {
+      'files'     => [],
+      'docs'      => []
+    }
+    
+    build.merge! preconfigured
+    
+    say "\nPlease enter the name of your App", :bold
+    build['appname'] = ask ">"
+  
+    say "\nPlease enter the javascript-files you want to integrate into your documentation", :bold
+    say "(You will be asked multiple times, unless your answer is empty) You also can specify a file-matching pattern, foo/**/*.js"
+    
+    while true do
+      answer = ask ">"
+      break if answer == ""
+      build['files'] << answer
+    end
+    
+    say "\nPlease enter the markdown-documentation-files you want to integrate into your documentation", :bold
+    say "(You will be asked multiple times, unless your answer is empty) You also can specify a file-matching pattern, like docs/*.md"
+    
+    while true do
+      answer = ask ">"
+      break if answer == ""
+      build['docs'] << answer
+    end
+    
+    if not build['templates'] and yes? "Are you using your own templates?"
+      say "\nPlease enter the path to your templates", :bold
+      build['templates'] = ask ">"
+    end
+    
+    if not build['output']
+      say "\nWhere do you wan't your documentation generated to? Please enter a path", :bold
+      build['output'] = ask ">"
+    end
+    
+    if not build['loglevel']
+      say "\nPlease specify the loglevel of your output: (error|warn|info|debug)", :bold
+      
+      while true do
+        answer = ask ">"
+        if %w(error warn info debug).include? answer
+          build['loglevel'] = answer
+          break
+        end
+        say "\nThe answer you've given is not one of (error|warn|info|debug). Please try again", :bold
+      end          
+    end
+    
+    if not build['logfile'] and yes? "Do you wan't to save your logs to a file?"
+      say "\nPlease enter the path to your logfile", :bold
+      build['logfile'] = ask ">"
+    end
+    
+    # answers[:scss_build] = yes? "Do you wan't to integrate SCSS into your build-process? #{yes_no}"
+    
+    # maybe ask some more information to generate build.yml
+    create_file output_file, build.to_yaml
+  end
+  
+  
+end
+
+if ARGV.size == 0
+  ARGV.unshift 'help'
+  
+elsif not (ARGV.size > 0 and DocJs.method_defined?(ARGV.first))
+  ARGV.unshift 'docjs'
+end
+
+DocJs.start(ARGV)

data/docjs.gemspec

@@ -4,8 +4,8 @@ Gem::Specification.new do |s|
 
 
   s.name = 'docjs'
-  s.version = '0.1.2'
-  s.date = '2011-06-07'
+  s.version = '0.1.3'
+  s.date = '2011-06-16'
   s.summary = "Javascript Documentation Generator"
   s.description = "Create beautyful Javascript documentations with this ruby-gem. It's pretty easy to customize and add your own tokens/DSL."
   s.homepage = "https://github.com/b-studios/doc.js"

data/lib/boot.rb

@@ -6,6 +6,7 @@ require_relative 'thor'
 require_relative 'logger'
 require_relative 'configs'
 require_relative 'parser/parser'
+require_relative 'token/handler'
 require_relative 'code_object/function'
 require_relative 'dom/dom'
 require_relative 'processor'
@@ -13,8 +14,8 @@ require_relative 'processor'
 def setup_application(options = {})
         
   # initialize Logger
-  Logger.setup :logfile => File.expand_path(options[:logfile], Dir.pwd),
-               :level   => (options[:loglevel]).to_sym
+  Logger.setup :logfile => (options[:logfile] && File.expand_path(options[:logfile], Dir.pwd)),
+               :level   => (options[:loglevel] || :info).to_sym
   
   Logger.info "Setting up Application"
   
@@ -31,4 +32,5 @@ def setup_application(options = {})
   Logger.debug "App Root:      #{Configs.root}"
   Logger.debug "Working Dir:   #{Configs.wdir}"
   Logger.debug "Output Dir:    #{Configs.output}"
-end
+  Logger.debug "Template Dir:  #{Configs.templates}"
+end

data/lib/code_object/base.rb

@@ -1,5 +1,6 @@
 # ../data.img#1787927:1
 require_relative '../token/container'
+require_relative '../token/handler'
 require_relative '../dom/dom'
 require_relative '../parser/meta_container'
 

data/lib/code_object/function.rb

@@ -15,64 +15,48 @@ module CodeObject
     # @todo i need a @prototype token in object
     def prototype
       children[:prototype]
-    end  
+    end
   
   end 
   
 end
 
 CodeObject::Type.register :function, CodeObject::Function
-Token::Handler.register :function, :handler => :noop, :area => :none
 
-# @todo rewrite as default-handler, because this looks a little distracting
 module Token::Handler
 
-  # @todo maybe allow multipled nested layers of params by parsing them recursivly
-  register :param, :area => :body do |tokenklass, content|
+  register :function, 
+           :handler => :noop, 
+           :area => :none,
+           :description => "Type-Token to categorize all kind of JavaScript-Functions"
+
+
+  # We want to support either named-typed-tokens like
+  #  @param [Foo] barname some description
+  #
+  # or multiline tokens like:
+  #  @param configs
+  #    Some configuration Object with following properties:
+  #    [String] foo some string
+  #    [Bar] bar and another one
+  #
+  # @note this can also be utilized for JavaScript-Event-Triggers or Callbacks with Parameters
+  register :param, :area => :none, :description => "Token for Function-Parameters like '@param [String] name your name'" do |tokenklass, content|
 
-    # We want to support either named-typed-tokens like
-    #  @param [Foo] barname some description
-    #
-    # or multiline tokens like:
-    #  @param configs
-    #    [String] foo some string
-    #    [Bar] bar and another one
-    #
-    #
-    # if out content matches something with `[` at the beginning, it seems to be
-    # a normal named-typed-token
-    # it's a little tricky because we still want to allow multiline descriptions of each param
-    def parse_token(content)  
-      typestring, name, content = TOKEN_W_TYPE_NAME.match(content).captures
-      types = typestring.split /,\s*/
-      Token::Token::ParamToken.new(:name => name, :types => types, :content => content)
-    end
-    
     # it's @param [String] name some content
     if content.lines.first.match TOKEN_W_TYPE_NAME
-      self.add_token parse_token(content)
+      self.add_token Token::Handler.apply(:typed_with_name, Token::Token::ParamToken, content)
     
     # it maybe a multiline
     else
-      lines = content.split(/\n/)
-      name = lines.shift.strip
-      types = ['PropertyObject']
-      
-      # now split line at opening bracket, not at line-break to enable multiline properties
-      children = lines.join("\n").strip.gsub(/\s+\[/, "<--SPLIT_HERE-->[").split("<--SPLIT_HERE-->")
-   
-      children.map! do |child|
-        parse_token(child)
-      end
-      
-      self.add_token tokenklass.new(:name => name, :types => types, :children => children)
+      self.add_token Token::Handler.apply(:named_nested_shorthand, Token::Token::ParamToken, content)
     end   
   end
 
 
 end
 
-Token::Handler.register :return, :handler => :typed
+Token::Handler.register :return, :handler => :typed, :area => :none, :description => "Returnvalue of a Function"
 Token::Handler.register :throws, :handler => :typed
 
 # MethodAlias