docjs 0.2 → 0.2.1

data/README.md

@@ -8,6 +8,10 @@ Doc.js is a JavaScript-Documentation tool which detects `tokens` in your comment
 documentation out of it. Doc.js could be ported pretty easy to any other language, because the most 
 of it's parts are language agnostic.
 
+Demo Projects
+-------------
+- [arrayJS](http://b-studios.github.com/arrayJS/)
+
 Features
 --------
 - One command to install
@@ -25,6 +29,13 @@ If you read this, you may belong to one of the following groups:
 2. You need some more {file:USE.md information, how to use Doc.js}
 3. You want to {file:CUSTOMIZE.md customize Doc.js}, to exactly fit your needs
 
+Useful Information
+------------------
+- List of supported {file:USE.md#Available_Tokens Tokens}
+- Built in {Token::Handler Handlers}
+- Overview about {Generator::Generator Generators}
+
+
 Supported Ruby-Version
 ----------------------
 Currently **only ruby > 1.9.x is supported**. Support for 1.8.x is not planned, because there are 
@@ -39,6 +50,9 @@ find the time to fix thoses and the first problem in 1.8.x so only 1.9+ is suppo
 the time to work on 1.8 compatibility you would make me (and possibly some other 1.8 users) very 
 happy.
 
+Architectural Insides
+---------------------
+{DocJs} is a good starting point if you want to get started with information about the structure of DocJs.
 
 Installation
 ------------

data/bin/docjs

@@ -3,53 +3,60 @@
 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
+# Program Flow
+# ------------
+# ![Program flow](img/md_total_flow.svg)
+#
+# 1. {#setup_application Prepare Doc.js} - Read configurations and setup application environment
+# 2. {Processor.prepare_documents Process Markdown Documents} - Read the optional markdown-documents and add them to the internal 
+#    datastructure.
+# 3. {Parser::Parser Process JavaScript Files} - Parse JavaScript-Files and add the found comments to the Dom. 
+#    Afterwards process the tokens within the comments.
+# 4. {Generator::Generator Render Templates} - Apply the Outputgenerators and save the rendered templates to disk
+# 5. Copy static resources - Finalize the output and copy the javascript, images and stylesheets to 
+#    the output-directory
+#
+# The {Processor} is the central module, which controls the workflow described above. It separates
+# the tasks into different stages, which are performed one after another. (You can see this in
+# the source-code of {DocJs#docjs})
+#
+# The Command Line Interface
+# --------------------------
+# The `DocJs`-class serves as command line interface (cli) and therefore extends Thor. It allows us 
+# to create tasks, which then in turn can be called from the command line.
+# This way every instance method of `DocJs` will be turned into a commandline task.
+#
+#     docjs help configure
+#
+# Will create an instance of DocJs and call the {#help} method on it. (Which results in the help screen
+# being displayed). As help expects one argument 'configure' is passed to the call of `help`. All 
+# additional commandline arguments would be parsed by Thor and added to the instance variable 
+# `configs`.
+#
+# The Internal Datastructure
+# --------------------------
+# All parsed CodeObjects (i.e. comments found in your JavaScript-soures) are internally represented
+# as a Dom-Tree. They can be accessed via {Dom.root}
+#
+# Also all Markdown-Documents are stored in the same Dom-tree, but under a different root-node called
+# {Dom.docs}.
+#
+# For more information about storing and retreiving Data in DocJs see {Dom}.
+#
+#
+# @see https://github.com/wycats/thor/wiki
+# @see Processor
 #
 # @note options declared in a docjs.yml will override command-line ones
+# @note for more information about the **instance methods** please type `docjs help` or 
+#   `docjs help TASK` into your commandline or reference the {file:README.md#Guides guides}.
 class DocJs < Thor
   
   include Thor::Actions
-  
-  def help(task = nil)
-  
-    # Introduction
-    unless task
-      say "Welcome to Doc.js", :bold
-      say "If you are using Doc.js for the first time in your project, you may want to create a config file (like docjs.yml)
-A guided wizard can help you achieving this goal - Simply run the following command:
-    docjs configure
-\n
-After creating a config-file (like docjs.yml) the documentation can be generated by running:
-    docjs docjs.yml
-
-For further information, please visit http://b-studios.github.com/doc.js\n\n"
-
-      self.class.help(shell, false)
       
-    # Help for a specific task
-    else
-      self.class.task_help(shell, task)    
-    end
-  end
-    
   desc "CONFIG_FILE", "Starts documentation process"
   set_options :files =>
                   { :type => :array,  :aliases => '-f', :default => [] },
@@ -78,10 +85,12 @@ For further information, please visit http://b-studios.github.com/doc.js\n\n"
     configs = config_file ? merge_options(options, config_file) : options
     
     begin
+      
+      # PREPARE DOCJS
+    
       # Setup Logger and Configs
       setup_application configs
       
-      # Load application specific files
       Logger.info "Loading Application-Templates"
       load_templates
       
@@ -89,24 +98,54 @@ For further information, please visit http://b-studios.github.com/doc.js\n\n"
       DocJs.source_root(Configs.templates)
       self.destination_root = Configs.output
       
-      # Process specified docs and add them to dom-tree
-      Processor.prepare_documents
       
-      # Kickoff js-file-processing and template-rendering!
-      Processor.process_and_render
+      # PROCESS MARKDOWN DOCUMENTS
+      Processor.prepare_documents     # Stage #1
+      
+      # PROCESS JAVASCRIPT FILES
+      Processor.process_files_to_dom  # Stage #2
+      
+      # RENDER TEMPLATES
+      Processor.start_generators      # Stage #3
+      
         
-      # Finally copy all
+      # COPY STATIC RESOURCES
       Logger.info "Copying template resources to output"
-      directory 'resources/img', './img' # copy resources
+      directory 'resources/img', './img'
       directory 'resources/css', './css'
       directory 'resources/js', './js'
-      
+    
+    # Print error on console, if something bad happend  
     rescue Exception => error
       Logger.error error.message + "\n" + error.backtrace.map{|l| "  #{l}" }.join("\n")
     end    
   end  
 
 
+
+  def help(task = nil)
+  
+    # Introduction
+    unless task
+      say "Welcome to Doc.js", :bold
+      say "If you are using Doc.js for the first time in your project, you may want to create a config file (like docjs.yml)
+A guided wizard can help you achieving this goal - Simply run the following command:
+    docjs configure
+\n
+After creating a config-file (like docjs.yml) the documentation can be generated by running:
+    docjs docjs.yml
+
+For further information, please visit http://b-studios.github.com/doc.js\n\n"
+
+      self.class.help(shell, false)
+      
+    # Help for a specific task
+    else
+      self.class.task_help(shell, task)    
+    end
+  end
+
+
   
   desc "configure [NEW_CONFIGFILE]", "Helps you creating your docjs.yml to start off with doc.js"
   def configure(output_file = "docjs.yml", preconfigured = {})

data/bin/docjs.rb

@@ -3,53 +3,60 @@
 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
+# Program Flow
+# ------------
+# ![Program flow](img/md_total_flow.svg)
+#
+# 1. {#setup_application Prepare Doc.js} - Read configurations and setup application environment
+# 2. {Processor.prepare_documents Process Markdown Documents} - Read the optional markdown-documents and add them to the internal 
+#    datastructure.
+# 3. {Parser::Parser Process JavaScript Files} - Parse JavaScript-Files and add the found comments to the Dom. 
+#    Afterwards process the tokens within the comments.
+# 4. {Generator::Generator Render Templates} - Apply the Outputgenerators and save the rendered templates to disk
+# 5. Copy static resources - Finalize the output and copy the javascript, images and stylesheets to 
+#    the output-directory
+#
+# The {Processor} is the central module, which controls the workflow described above. It separates
+# the tasks into different stages, which are performed one after another. (You can see this in
+# the source-code of {DocJs#docjs})
+#
+# The Command Line Interface
+# --------------------------
+# The `DocJs`-class serves as command line interface (cli) and therefore extends Thor. It allows us 
+# to create tasks, which then in turn can be called from the command line.
+# This way every instance method of `DocJs` will be turned into a commandline task.
+#
+#     docjs help configure
+#
+# Will create an instance of DocJs and call the {#help} method on it. (Which results in the help screen
+# being displayed). As help expects one argument 'configure' is passed to the call of `help`. All 
+# additional commandline arguments would be parsed by Thor and added to the instance variable 
+# `configs`.
+#
+# The Internal Datastructure
+# --------------------------
+# All parsed CodeObjects (i.e. comments found in your JavaScript-soures) are internally represented
+# as a Dom-Tree. They can be accessed via {Dom.root}
+#
+# Also all Markdown-Documents are stored in the same Dom-tree, but under a different root-node called
+# {Dom.docs}.
+#
+# For more information about storing and retreiving Data in DocJs see {Dom}.
+#
+#
+# @see https://github.com/wycats/thor/wiki
+# @see Processor
 #
 # @note options declared in a docjs.yml will override command-line ones
+# @note for more information about the **instance methods** please type `docjs help` or 
+#   `docjs help TASK` into your commandline or reference the {file:README.md#Guides guides}.
 class DocJs < Thor
   
   include Thor::Actions
-  
-  def help(task = nil)
-  
-    # Introduction
-    unless task
-      say "Welcome to Doc.js", :bold
-      say "If you are using Doc.js for the first time in your project, you may want to create a config file (like docjs.yml)
-A guided wizard can help you achieving this goal - Simply run the following command:
-    docjs configure
-\n
-After creating a config-file (like docjs.yml) the documentation can be generated by running:
-    docjs docjs.yml
-
-For further information, please visit http://b-studios.github.com/doc.js\n\n"
-
-      self.class.help(shell, false)
       
-    # Help for a specific task
-    else
-      self.class.task_help(shell, task)    
-    end
-  end
-    
   desc "CONFIG_FILE", "Starts documentation process"
   set_options :files =>
                   { :type => :array,  :aliases => '-f', :default => [] },
@@ -78,10 +85,12 @@ For further information, please visit http://b-studios.github.com/doc.js\n\n"
     configs = config_file ? merge_options(options, config_file) : options
     
     begin
+      
+      # PREPARE DOCJS
+    
       # Setup Logger and Configs
       setup_application configs
       
-      # Load application specific files
       Logger.info "Loading Application-Templates"
       load_templates
       
@@ -89,24 +98,54 @@ For further information, please visit http://b-studios.github.com/doc.js\n\n"
       DocJs.source_root(Configs.templates)
       self.destination_root = Configs.output
       
-      # Process specified docs and add them to dom-tree
-      Processor.prepare_documents
       
-      # Kickoff js-file-processing and template-rendering!
-      Processor.process_and_render
+      # PROCESS MARKDOWN DOCUMENTS
+      Processor.prepare_documents     # Stage #1
+      
+      # PROCESS JAVASCRIPT FILES
+      Processor.process_files_to_dom  # Stage #2
+      
+      # RENDER TEMPLATES
+      Processor.start_generators      # Stage #3
+      
         
-      # Finally copy all
+      # COPY STATIC RESOURCES
       Logger.info "Copying template resources to output"
-      directory 'resources/img', './img' # copy resources
+      directory 'resources/img', './img'
       directory 'resources/css', './css'
       directory 'resources/js', './js'
-      
+    
+    # Print error on console, if something bad happend  
     rescue Exception => error
       Logger.error error.message + "\n" + error.backtrace.map{|l| "  #{l}" }.join("\n")
     end    
   end  
 
 
+
+  def help(task = nil)
+  
+    # Introduction
+    unless task
+      say "Welcome to Doc.js", :bold
+      say "If you are using Doc.js for the first time in your project, you may want to create a config file (like docjs.yml)
+A guided wizard can help you achieving this goal - Simply run the following command:
+    docjs configure
+\n
+After creating a config-file (like docjs.yml) the documentation can be generated by running:
+    docjs docjs.yml
+
+For further information, please visit http://b-studios.github.com/doc.js\n\n"
+
+      self.class.help(shell, false)
+      
+    # Help for a specific task
+    else
+      self.class.task_help(shell, task)    
+    end
+  end
+
+
   
   desc "configure [NEW_CONFIGFILE]", "Helps you creating your docjs.yml to start off with doc.js"
   def configure(output_file = "docjs.yml", preconfigured = {})

data/docjs.gemspec

@@ -4,8 +4,8 @@ Gem::Specification.new do |s|
 
 
   s.name = 'docjs'
-  s.version = '0.2'
-  s.date = '2011-06-28'
+  s.version = '0.2.1'
+  s.date = '2012-10-06'
   s.summary = "Javascript Documentation Generator"
   s.description = "Create beautiful 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/docs/guides/CUSTOMIZE.md

@@ -1,3 +1,93 @@
+Customization
+=============
+All of the following Guides require modifications of the default-templates. To start of with your own
+templates simply type:
+
+    docjs scaffold TEMPLATE_PATH
+    
+in your console and replace `TEMPLATE_PATH` with the path you wish the templates to be generated in.
+This command will copy the default templates to `TEMPLATE_PATH`, which results in a structure similiar
+to:
+
+    my_templates/
+      generators/
+      helpers/
+      resources/
+      tokens/
+      types/
+      views/
+      application.rb
+      
+If you take a look at `application.rb` you will see, that all it does is to require the files, which 
+are placed within the other template-folders.
+
+generators/
+-----------
+Contains all custom generators, which are needed to create html or json-files from the internal data-
+structure. In section {file:CUSTOMIZE.md#Modifying_a_Generator Modifying a Generator} you can learn
+a bit more about the use of a generator and how to customize it.
+
+**Contents:**
+
+  - {Generator::ApiIndexGenerator}
+  - {Generator::ApiPagesGenerator}
+  - {Generator::DocsGenerator}
+  - {Generator::JsonGenerator}
+
+helpers/
+--------
+Helpers are, like helpers in Rails, included into your generator and can be used there and in the views
+aswell. (See Section Helpers in {Generator::Generator})
+
+**Contents:**
+
+  - {Helper::Template}
+
+resources/
+----------
+Contains all static template resources like **css**, **js** and **img** files
+
+**Contents:**
+
+  - `css/application.css`
+  - `scss/application.scss` and all partials (starting with an underscore)
+  - `js/application.js` and all required libraries
+  - `img/object.png` and all other icons
+
+tokens/
+-------
+Only consists of one file `tokens.rb`, which contains all the registered Tokens. You may find some more 
+information about the tokens in the {file:USE.md Usage-Guide}.
+
+**Contents:**
+
+  - `tokens.rb`
+
+types/
+------
+Types are special tokens. They categorize the Comments respectively CodeObject's by subclassing them.
+Per default these are
+
+**Contents:**
+
+  - {CodeObject::Object} (@object)
+  - {CodeObject::Function} (@function, @constructor, @method)
+  - {CodeObject::Prototype} (@prototype)
+
+See {file:USE.md#Types Usage-Guide}
+
+views/
+------
+Contains the `html.erb` template-files and partials, which will be rendered by the {Generator::Generator Generators}
+
+**Contents:**
+
+  - `function/` All templates to render {CodeObject::Function @function-documentation}
+  - `object/` All templates to render {CodeObject::Object @object-documentation}
+  - `layouts/` Contains all layouts like `application.html.erb` and `json.html.erb`
+  - `tokens/` All templates, which a necessary to render a token (See {file:CUSTOMIZE.md#Creating_a_custom_template the Guide below})
+
+
 1. Example - Adding a simple token
 ==================================
 You can extend Doc.js on different levels. The easiest way of customization is to add a simple token.