Made layout files editable by users

README

@@ -9,17 +9,18 @@ It generates a set of HTML views in the public directory.  Parses the desired co
 Currently does not read routes.rb and requires manual entry of routes
 
 =INSTALL
-    script/plugin install git://github.com/fmiopensource/rapi_doc
+    gem install rapi_doc
 
-==Templates
-Templates can be used for tuning your method generation and index.html.erb.
+==Layout files
+You can find documentation layouts in config/rapi_doc
 
-==Structure
-In the structure folder one can setup some additional views to be used for the apidoc controller generator.
+index.html.erb is used for index page.
+resource.html.erb is used for individual controllers.
 
 ==Usage
-Create a documentation.yml inside your config directory.  In this config file specify the controllers you wish to
-generate documentation for in the following format:
+Run 'rake rapi_doc' to generate config and layout files. (TODO: Add a separte rake task to generate config files)
+Modify config file by adding your controllers, e.g.:
+
 users:
   location: "/users"
   controller_name: "users_controller.rb"
@@ -40,6 +41,3 @@ param:: per_page:int - max items per page, default is 10
 Get a list of all users in the system with pagination.  Defaults to 10 per page
 =end
 
-=======================
-TODO  - Make class documentation work
-      - Write tests and make them work

lib/config.rb

@@ -0,0 +1,25 @@
+module Config
+  def config_dir
+    File.join(::Rails.root.to_s, 'config/rapi_doc')
+  end
+
+  def template_dir
+    File.join(File.dirname(__FILE__), '/../templates')
+  end
+
+  def target_config_file
+    File.join(config_dir,   'config.yml')
+  end
+
+  def template_config_file
+    File.join(template_dir, 'config.yml')
+  end
+
+  def index_layout_file
+    File.join(config_dir, 'index.html.erb')
+  end
+
+  def resource_layout_file
+    File.join(config_dir, 'resource.html.erb')
+  end
+end

lib/rapi_doc.rb

@@ -2,7 +2,10 @@
 require 'fileutils'
 require File.dirname(__FILE__) + '/doc_util.rb'
 require File.dirname(__FILE__) + '/resource_doc.rb'
-#
+require File.dirname(__FILE__) + '/config'
+
+include Config # TODO FIXME
+
 class RAPIDoc
 
   # Initalize the ApiDocGenerator
@@ -29,16 +32,11 @@ def generate_templates!
   # generate the index file for the api views
   def generate_index!
     template = ""
-    File.open(File.join(File.dirname(__FILE__), '..', 'templates', 'index.html.erb.erb')).each { |line| template << line }
+    File.open(index_layout_file).each { |line| template << line }
     parsed = ERB.new(template).result(binding)
     File.open(File.join(File.dirname(__FILE__), '..', 'structure', 'views', 'apidoc',"index.html"), 'w') { |file| file.write parsed }
   end
 
-  # TODO
-  def make_backups!
-    puts "TODO"
-  end
-
   def move_structure!
     target_folder = "#{::Rails.root.to_s}/public/apidoc/"
 
@@ -59,7 +57,6 @@ def move_structure!
 
   def copy_styles!
     Dir[File.join(File.dirname(__FILE__), '..', 'templates/*')].each do |f|
-      puts f 
       if f =~ /[\/a-zA-Z\.]+\.css$/i
         FileUtils.cp f, File.join(File.dirname(__FILE__), '..', '/structure/views/apidoc/')
       end

lib/resource_doc.rb

@@ -46,34 +46,20 @@ def parse_apidoc!
     File.open(controller_location).each do |line|
       if line =~ /=begin apidoc/
         current_scope = !inclass ? :class : :function
-        puts "-"*30
-        puts ">>> found: =begin apidoc"
-        puts "scope: #{current_scope}"
-        puts "-"*30; puts ""
         current_api_block = MethodDoc.new(current_scope)
       elsif line =~ /=end/
         if current_api_block.nil?
           puts "#{controller_location}:#{lineno} - No starttag for =end found"
           exit
         elsif current_api_block.scope == :class
           @class_block = current_api_block
-
-          puts "-"*30
-          puts ">>> current_api_block.scope == :class"
-          puts "#{@class_block}"
-          puts "-"*30; puts ""
-
         elsif current_api_block.scope == :function
           @function_blocks << current_api_block
         end
         current_api_block = nil
         current_scope = :none
       elsif line =~ /class/
-        inclass=true
-        puts "-"*30
-        puts ">>> found class"
-        puts "scope: #{current_scope}"
-        puts "-"*30; puts ""
+        inclass = true
       elsif line =~ /::response-end::/
         current_scope = :function
       elsif line =~ /::request-end::/
@@ -88,7 +74,6 @@ def parse_apidoc!
         # check if we are dealing with a variable
         # something in the format: # varname:: sometext
         if result = /(\w+)\:\:\s*(.+)/.match(line)
-          puts "calling current_api_block.add_variable()"
           if result[1] == "response" || result[1] == "request"
             puts "="*30
             puts "found response"
@@ -106,7 +91,7 @@ def parse_apidoc!
       lineno += 1
     end
 
-    puts "Documented #{name}"
+    puts "Generated #{name}.html"
   end
 
   def generate_view!(resources)
@@ -117,17 +102,15 @@ def generate_view!(resources)
      end
      # write it to a file
      template = ""
-     File.open(File.join(File.dirname(__FILE__), '..', 'templates', 'resource.html.erb.erb')).each { |line| template << line }
+     File.open(resource_layout_file).each { |line| template << line }
      parsed = ERB.new(template).result(binding)
      File.open(File.join(File.dirname(__FILE__), '..', 'structure', 'views', 'apidoc', name + ".html"), 'w') { |file| file.write parsed }
-
   end
 
 
   def get_parsed_header
-
     template = ""
-    File.open(File.join(File.dirname(__FILE__), '..', 'templates', '_resource_header.html.erb.erb')).each { |line| template << line }
+    File.open(File.join(File.dirname(__FILE__), '..', 'templates', '_resource_header.html.erb')).each { |line| template << line }
 
     puts "-"*30
     puts ">>> inside: get_parsed_header"
@@ -140,7 +123,7 @@ def get_parsed_header
 
   def get_parsed_method(method_block)
     template = ""
-    File.open(File.join(File.dirname(__FILE__), '..', 'templates', '_resource_method.html.erb.erb')).each { |line| template << line }
+    File.open(File.join(File.dirname(__FILE__), '..', 'templates', '_resource_method.html.erb')).each { |line| template << line }
     return ERB.new(template).result(method_block.get_binding)
   end
 

lib/tasks/rapi_doc_tasks.rake

@@ -3,17 +3,14 @@ require File.dirname(__FILE__) + '/../../lib/rapi_doc.rb'
 desc "Generate the API Documentation"
 task :rapi_doc do
 
-  config_dir   = File.join(::Rails.root.to_s, 'config/rapi_doc')
-  template_dir = File.join(File.dirname(__FILE__), '/../../templates')
-  target_config_file   = File.join(config_dir,   'config.yml')
-  template_config_file = File.join(template_dir, 'config.yml')
-
   begin
-    yml = YAML::load(File.open(targe_config_file))
+    yml = YAML::load(File.open(target_config_file))
   rescue
     FileUtils.mkdir(config_dir)
     FileUtils.cp template_config_file, target_config_file
-    puts "Generated config/rapi_doc/config.yml."
+    FileUtils.cp index_layout_file, config_dir
+    FileUtils.cp resource_layout_file, config_dir
+    puts "Generated config/rapi_doc/config.yml." # TODO Add instructions for users to update the config file
   end
 
   # Generating documentations

templates/index.html.erb

@@ -0,0 +1,67 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <title><%= @name || 'Home' %></title>
+
+    <style>
+      body {
+        line-height: 1.5em;
+        color:#484848;
+      }
+
+      ul, ol {
+        margin-bottom: 0.8em;
+      }
+
+      li {
+        padding-left: 10px;
+        margin-right: 10px;
+      }
+
+      #resources {
+
+      }
+
+      h1, h2, h3 {
+        padding-top: 8px;
+        padding-bottom: 2px;
+      }
+
+      #method {
+        padding: 15px 30px;
+        border-top:1px solid #ddd;
+      }
+
+      #http_verb {
+        color:#ff6600;
+        width:200px;
+        margin-right:20px;'
+      }
+
+      .description{
+        font-size: 1.4em;
+        color:#262626;
+      }
+    </style>
+
+  </head>
+  <body>
+    <div class="content">
+
+      <div id="introduction">
+        <!-- documentation intro -->
+      </div>
+
+      <h2>Resources</h2>
+      <div id="resources">
+        <ul>
+        <% @resources.each do |r| %>
+          <li>Resource:  <a href="/apidoc/<%=r.name %>.html"><%=r.resource_location %></a></li>
+        <% end %>
+        </ul>
+      </div>
+
+    </div>
+  </body>
+</html>