docjs 0.1 → 0.1.2

data/README.md

@@ -1,19 +1,82 @@
-jsdoc
-=====
-After total dataloss i have to rewrite the Readme's and Test's, so please be patient.
-jsdoc is currently **not a bit** stable. Stay tuned.
-
-For some more information about the architecture see:
-
-  - {Parser}  
-  - {CodeObject}
-  - {Token}
-  - {Dom}  
-  - {Renderer}
-  
-The 'executable' is {JsDoc}
+Doc.js
+======
+Just a note: After total dataloss i have to rewrite the Readme's and Test's, so 
+please be patient.
+
+
+Supported Ruby-Version
+======================
+Currently **only > 1.9** is supported. I am working on 1.8.x, though this is not 
+my target platform.
+
+
+Installation
+============
+    gem install docjs    
+
 
 Required Gems
 =============
+The following Gems are required to make docjs work and should automatically be 
+installed while installing docjs:
+
   - thor
   - rdiscount
+  
+
+Basic Usage
+===========
+
+Configuration
+-------------
+Before you can use Doc.js you may create your own **Configuration-File**. This 
+can easily be done, using the built-in 
+configuration-generator:
+
+    docjs configure
+    
+You optionally can specify the filename of your configuration file. If no file 
+is specified the configs will be written to `build.yml`.
+
+    docjs configure my_config_file.yml
+
+The configuration is an interactive one - simply answer the questions you will 
+be asked.
+
+
+Start documenting your code
+---------------------------
+To make jsdoc recognize your documentation you have to use some special tokens.
+Let's write a documented function `hello_doc`:
+    
+    /**
+     * @function hello_doc
+     *
+     * Innovative function to greet a Person.
+     *
+     * @param [String] name the person you want to greet
+     * @return void
+     */
+    function hello_doc(name) {
+      console.log("Hello " + name + "!");
+    }
+    
+The symbols `@function`, `@param` and `@return` are called **tokens** in Doc.js. 
+There are many more by default. To see which one you can use simply type:
+
+    docjs tokens
+  
+
+Run the documentation and enjoy!
+--------------------------------
+Now it's time to kickoff the documentation-process by typing:
+
+    docjs your_config.yml
+
+You will find the docs in the output-directory you have specified in your 
+config-file.
+
+
+License
+=======
+docjs is released under MIT-License. See LICENSE.md for more information.

data/bin/docjs

@@ -26,11 +26,11 @@ Configs.set :root  => Pathname.new(__FILE__).realpath + '../..'
 # @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 JsDoc < Thor
+class DocJs < Thor
     
   include Thor::Actions
     
-  desc "jsdoc CONFIG_FILE", "Starts documentation process"
+  desc "CONFIG_FILE", "Starts documentation process"
   set_options :files =>
                   { :type => :array,  :aliases => '-f', :default => [], :required => true },
                
@@ -47,12 +47,12 @@ class JsDoc < Thor
                   { :type => :string, :aliases => '-n', :default => "MyAppName" },
                   
               :logfile =>
-                  { :type => :string, :aliases => '-lf', :default => 'jsdoc.log' },
+                  { :type => :string, :aliases => '-lf', :default => 'docjs.log' },
                   
               :loglevel =>
                   { :type => :string, :aliases => '-ll', :default => 'info' }
   
-  def jsdoc(config_file = nil)
+  def docjs(config_file = nil)
     # @see Thor#merge_options
     configs = config_file ? merge_options(options, config_file) : options
     
@@ -63,7 +63,7 @@ class JsDoc < Thor
       require Configs.templates + '/application.rb'
       
       # Config Thor settings
-      JsDoc.source_root(Configs.templates)
+      DocJs.source_root(Configs.templates)
       self.destination_root = Configs.output
       
       Processor.prepare_documents
@@ -119,20 +119,20 @@ class JsDoc < Thor
     })
     
     # Setup Thor paths
-    JsDoc.source_root(Configs.root)
+    DocJs.source_root(Configs.root)
     self.destination_root = Configs.output
-    Configs.set(:scaffolding_path, output_dir)
-    
-    
-    answers = {}    
+
     yes_no = "(y|n)"
     
-    Logger.info "We need some information from you, to customize the scaffolding process to your needs."
-    
-    answers[:build] = yes? "Do you wan't to generate a build.yml? #{yes_no}"
-    write_build_file if answers[:build]
-    
-    Configs.set :answers, answers
+    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}"
@@ -141,20 +141,16 @@ class JsDoc < Thor
     Logger.info "Copying the included *.rb files to #{Configs.includes}"    
   end
   
-  
-  protected
-  
-  def write_build_file
-  
+  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'      => [],
-      'output'    => 'docs',
-      'logfile'   => 'logfile.log',
-      'loglevel'  => 'info',
-      'templates' => Configs.scaffolding_path
+      'docs'      => []
     }
     
+    build.merge! preconfigured
+    
     say "\nPlease enter the name of your App", :bold
     build['appname'] = ask ">"
   
@@ -176,15 +172,43 @@ class JsDoc < Thor
       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['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 Configs.wdir + "/build.yml", build.to_yaml
+    create_file output_file, build.to_yaml
   end
   
+  
 end
 
-unless ARGV.first and JsDoc.method_defined?(ARGV.first)
-  ARGV.unshift 'jsdoc'
+if ARGV.size == 0
+  ARGV.unshift 'help'
+  
+elsif not (ARGV.size > 0 and DocJs.method_defined?(ARGV.first))
+  ARGV.unshift 'docjs'
 end
-JsDoc.start(ARGV)
+
+DocJs.start(ARGV)

data/docjs.gemspec

@@ -4,11 +4,11 @@ Gem::Specification.new do |s|
 
 
   s.name = 'docjs'
-  s.version = '0.1'
+  s.version = '0.1.2'
   s.date = '2011-06-07'
   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/docjs"
+  s.homepage = "https://github.com/b-studios/doc.js"
   s.authors = ["Jonathan Brachthäuser"]
   s.email = "jonathan@b-studios.de"
   s.rubyforge_project = s.name

data/lib/boot.rb

@@ -1,6 +1,6 @@
 require 'thor'
-require 'json'
 require 'yaml'
+require 'json'
 
 require_relative 'thor'
 require_relative 'logger'
@@ -10,7 +10,7 @@ require_relative 'code_object/function'
 require_relative 'dom/dom'
 require_relative 'processor'
 
-def setup_application(options)
+def setup_application(options = {})
         
   # initialize Logger
   Logger.setup :logfile => File.expand_path(options[:logfile], Dir.pwd),

data/lib/logger.rb

@@ -16,7 +16,7 @@ module Logger
   def self.setup(args = {})
 
     @@shell = Thor::Base.shell.new
-    @@logfile = args[:file] 
+    @@logfile = args[:logfile] 
     @@level   = LEVEL[args[:level] || :info]
     
     # write start sequence
@@ -37,7 +37,7 @@ module Logger
     
     msg = msg.join "\n"
     
-    unless @@logfile.nil?      
+    unless @@logfile.nil? or @@logfile == ""    
       File.open(@@logfile, "a") do |f|
         f.write "#{level.prefix} #{msg}\n"
       end

data/templates/tasks/json_data_task.rb

@@ -52,4 +52,4 @@ module Tasks
   end
 end
 
-Processor.register_render_task :json_data, Tasks::JsonDataTask
+Processor.register_render_task :json_data, Tasks::JsonDataTask

data/test/code_object/prototype.rb

@@ -1,5 +1,6 @@
 # ../data.img#1774507:1
 require_relative '../../lib/boot'
+require_relative '../../templates/types/prototype'
 
 describe CodeObject::Prototype, ".new" do
 

data/test/rspec_helper.rb

@@ -1,3 +1,6 @@
+# This is a fix, because JSON::Parser has to be registered before our Parser-Module
+require 'json'
+
 def should_raise(exception_type, &block)    
   begin
     block.call    
@@ -20,4 +23,4 @@ class Object
     self.content.should == content
   end
   
-end
+end

data/test/token/tokens.rb

@@ -1,6 +1,7 @@
 require_relative '../../lib/parser/comment'
 require_relative '../../lib/code_object/function'
-require_relative '../../lib/token/tokens'
+
+require_relative '../../templates/tokens/tokens'
 
 describe Token::Handler, ".register" do
   

metadata

@@ -2,7 +2,7 @@
 name: docjs
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: "0.1"
+  version: 0.1.2
 platform: ruby
 authors: 
 - "Jonathan Brachth\xC3\xA4user"
@@ -153,7 +153,7 @@ files:
 - test/token/handler.rb
 - test/token/tokens.rb
 has_rdoc: true
-homepage: https://github.com/b-studios/docjs
+homepage: https://github.com/b-studios/doc.js
 licenses: []
 
 post_install_message: