rain-doc 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0d3e2da94026e3479875b443e8557932639117a5
-  data.tar.gz: 15a5d5ec27b9134d6f907dcc164f26c61727fe89
+  metadata.gz: 2ac2daf49d1502a2f8042be98b8bcf2f0a8c285f
+  data.tar.gz: 55fa316386cf105a6c5fe59b0deac896e0e27156
 SHA512:
-  metadata.gz: 43155c813198015ec8c7fc36b9539d460a79c9e136bf7aee7e7a66f5025b1f3e695c20cf3c8242c01c6940980cf57bade86ee7002ba06b80ee29cdddd0f9c13f
-  data.tar.gz: 14b6f9aca5e9f470eb67dc4e7f40cba480eb886a44473085c893a76ea9f5fb40143121a82193e6fc0d1dbce997b63882147183fb30d97ae0b6ea77d2ab30a36d
+  metadata.gz: 45a73cb660db67b8a21a012dbf1c05e32d70d853ddbdf4ec805e9c4600e0ccce561e309605c9cbabb55b74f37e86e19bdf81b5dd97a44258c5f789d75de72994
+  data.tar.gz: 90634848c3256aa1261a72e234f7df6216d0c4bafa9a77b8618b04be8f2bcc9104d9e20f8f8c2f3e0ca6d09c5b82c9ad8ea37e33347e081b0e48803699b093df

data/lib/doc.rb

@@ -18,10 +18,11 @@ module Rain
     @@open_param_type = nil
     @@open_param_default = nil
     @@log_lines = false
+    @@parse_signatures = false
 
     # sets up the doc using the file name and contents
     # as a basis.
-    def initialize(file_name, file_contents, log_lines = false)
+    def initialize(file_name, file_contents, log_lines = false, parse_signatures = false)
 
       # set up basic options and defaults
       self.file_name = file_name
@@ -30,6 +31,7 @@ module Rain
       self.parts = []
       self.lines = 0
       @@log_lines = log_lines
+      @@parse_signatures = parse_signatures
 
       # set the doc type based on extension
       case self.file_ext
@@ -69,7 +71,7 @@ module Rain
       self.file_contents.each_line do |line|
 
         # parse the current line
-        result = self.parser.parse(line)
+        result = self.parser.parse(line, @@parse_signatures)
 
         # if there is no documentation for the result,
         # create a new part and then set the current part to nil.
@@ -95,6 +97,8 @@ module Rain
           self.current_part.set_route(result[:route])
         when :method
           self.current_part.set_method(result[:method])
+        when :signature
+          self.current_part.set_signature(result[:text])
         when :response
 
           # open the current response tag using the code as a key
@@ -133,9 +137,9 @@ module Rain
       # add the part and create a new one
       self.new_part
 
-      # remove any empty parts (for ruby docs)
+      # remove any empty parts or parts without method signatures (for ruby docs)
       if self.type == :RUBY
-        self.parts = self.parts.select{ |part| part.route != "//" }
+        self.parts = self.parts.select{ |part| part.route != "//" || !part.signature.nil? }
       end
     end
 

data/lib/doc_part.rb

@@ -1,6 +1,9 @@
 module Rain
+
+  # the doc part is a model to store information about
   class DocPart
-    attr_accessor :http_method, :responses, :route, :doc, :params, :headers
+
+    attr_accessor :http_method, :responses, :route, :doc, :params, :headers, :signature
 
     def initialize
       self.responses = []
@@ -124,6 +127,16 @@ module Rain
       return header[:text]
     end
 
+    # sets a method signature
+    def set_signature(sig)
+      self.signature = sig
+    end
+
+    # gets the method signature
+    def get_signature
+      self.signature
+    end
+
     def to_hash
       return {
         route: self.route,
@@ -131,7 +144,8 @@ module Rain
         headers: self.headers,
         doc: self.doc,
         responses: self.responses,
-        http_method: self.http_method
+        http_method: self.http_method,
+        signature: self.signature
       }
     end
   end

data/lib/parser.rb

@@ -16,9 +16,18 @@ module Rain
     # parses the current line, determining which tag
     # the line contains and returning the result
     # accordingly in a hash with the tag type
-    def parse(line)
+    def parse(line, parse_signatures = false)
+
       # return nil if there is no # on the line for ruby.
-      return nil if self.type == :RUBY && !line.strip().start_with?('#')
+      basic_stripped = line.strip().sub(' do', '')
+      return nil if self.type == :RUBY && basic_stripped == ''
+
+      # see if a signature part can be extracted if a signature is enabled
+      if parse_signatures
+        return nil if self.type == :RUBY && !basic_stripped.start_with?('#') && !(basic_stripped =~ /class|def|get|put|post|delete/)
+      else
+        return nil if self.type == :RUBY && !basic_stripped.start_with?('#')
+      end
 
       # strip blanks and # from the current line
       line = strip_current_line(line)
@@ -77,6 +86,16 @@ module Rain
         }
       end
 
+      # return method signature if found
+      if parse_signatures
+        if line.start_with?('def ', 'class ', 'get "', "get '", 'put "', "put '", 'post "', "post '", 'delete "', "delete '")
+          return {
+            tag: :signature,
+            text: line
+          }
+        end
+      end
+
       # return simple doc line if no tags fit
       return {
         tag: :doc,

data/lib/rain.rb

@@ -7,14 +7,15 @@ class Rain::CLI < Thor
 	@@docs = []
 
 	desc "generate [file/sources/**]", "Generates the rain documentation"
-	method_option :log_parse, aliases: "--lp", desc: "Show the output of each line parse"
+	method_option :log_parse, aliases: "--lp", desc: "Show the output of each line parse."
+	method_option :parse_signatures, aliases: "--s", desc: "Parse method and class documentation too. Defaults to false."
 	def generate(*sources)
 		print "Rain is parsing files in the directories #{sources} \n"
 
 		# loop through all of the file sources and generate docs
 		sources.each do |source|
 			print "Parsing #{source} \n"
-			@doc = Rain::Doc.new(source, File.read(Dir.pwd + "/#{source}"), options[:log_parse])
+			@doc = Rain::Doc.new(source, File.read(Dir.pwd + "/#{source}"), options[:log_parse].nil? ? false : true, options[:parse_signatures].nil? ? false : true)
 			@doc.parse
 
 			@@docs << @doc
@@ -41,6 +42,8 @@ class Rain::CLI < Thor
 	end
 
 	no_commands do
+
+		# Builds the HTML for each doc in the @@docs array.
 		def build_html
 
 			# delete the old output files and create the dir
@@ -57,6 +60,7 @@ class Rain::CLI < Thor
 				# load the templates
 				layout_template = File.read('./templates/layout.erb')
 				doc_template = File.read('./templates/doc.erb')
+				nav_template = File.read('./templates/nav.erb')
 
 			else
 
@@ -67,6 +71,51 @@ class Rain::CLI < Thor
 				# load the templates
 				layout_template = File.read(spec.gem_dir + '/templates/layout.erb')
 				doc_template = File.read(spec.gem_dir + '/templates/doc.erb')
+				nav_template = File.read(spec.gem_dir + '/templates/nav.erb')
+			end
+
+			# loop through all of the docs and generate navigation from the docs and their parts
+			nav_parts = []
+			@@docs.each do |doc|
+
+				# get the html file name (same used for output) from the doc openstruct
+				doc_os = OpenStruct.new(doc.to_hash)
+				html_file_name = File.basename(doc_os.file_name, doc_os.file_ext) + '.html'
+
+				# set up the nav hash for the doc
+				nav = {
+					navdoc: {
+						title: doc_os.title,
+						url: "#{html_file_name}",
+						parts: []
+					}
+				}
+
+				# markdown docs do not have parts as the whole page counts as a "doc"
+				if doc_os.type != "MARKDOWN"
+
+					# loop through all of the parts and depending on whether
+					# it is for a signature or a route, construct the #anchor
+					# url differnetly
+					doc_os.parts.each do |part|
+						if !part[:signature].nil?
+							nav[:navdoc][:parts] << {
+								title: part[:signature],
+								url: "#{html_file_name}##{part[:signature].gsub(' ', '-').gsub(',', '').gsub('(', '-').gsub(')', '-')[0..12]}"
+							}
+						else
+							nav[:navdoc][:parts] << {
+								title: part[:route],
+								url: "#{html_file_name}##{part[:route].gsub('/', '-').gsub(':', '')}"
+							}
+						end
+					end
+				end
+
+				# render the nav and append it to the array of nav parts
+				nav_os = OpenStruct.new(nav)
+				nav_rendered = ERB.new(nav_template).result(nav_os.instance_eval {binding})
+				nav_parts << nav_rendered
 			end
 
 			# load the doc properties and parts into the doc template
@@ -74,11 +123,10 @@ class Rain::CLI < Thor
 
 				# create an openstruct from the current doc and render into the template
 				doc_os = OpenStruct.new(doc.to_hash)
-
 				doc_rendered = ERB.new(doc_template).result(doc_os.instance_eval {binding})
 
-				# create a struct with the rendered doc output then render into the layout
-				layout_os = OpenStruct.new({ doc_output: doc_rendered, title: doc_os.title })
+				# create a struct with the rendered doc output then render into the layout with nav
+				layout_os = OpenStruct.new({ doc_output: doc_rendered, title: doc_os.title, nav_parts: nav_parts })
 				html = ERB.new(layout_template).result(layout_os.instance_eval {binding})
 
 				# write the html to a file
@@ -86,7 +134,17 @@ class Rain::CLI < Thor
 			end
 		end
 
+		# Creates the html file for the specified doc
+		# with the HTML rendered from the ERB template
+		# 
+		# {param doc hash}
+		# 	A hash representation of the Rain::Doc class, containing a single document and its parts.
+		# {/param}
+		# {param html string}
+		# 	The HTML rendered from the ERB layout and doc template.
+		# {/param}
 		def output_html(doc, html)
+
 			# replace file_name extenstions with .html
 			file_name = File.basename(doc.file_name, doc.file_ext) + '.html'
 

data/templates/doc.erb

@@ -3,13 +3,15 @@
 
   <!-- HTTP method and route (if both specified) -->
   <% if !part[:route].nil? && !part[:http_method].nil? %>
-    <p><strong><%= part[:http_method] %></strong> <%= part[:route] %></p>
+    <p id="<%= part[:route].gsub('/', '-').gsub(':', '') %>"><strong><%= part[:http_method] %></strong> <%= part[:route] %></p>
+  <% elsif !part[:signature].nil? %>
+    <p id="<%= part[:signature].gsub(' ', '-').gsub(',', '').gsub('(', '-').gsub(')', '-')[0..12] %>"><strong><%= part[:signature] %></strong></p>
   <% end %>
 
   <!-- display all of the docs together for the part -->
-  <% part[:doc].each do |doc| %>
-    <p><%= doc %></p>
-  <% end %>
+  <p><% part[:doc].each do |doc| %>
+    <%= doc %>
+  <% end %></p>
 
   <!-- show all of the params in a table -->
   <% if part[:params].length > 0 %>

data/templates/layout.erb

@@ -6,9 +6,17 @@
 </head>
 <body>
   <div class="container">
-    <div class="twelve columns" style="padding: 20px 0">
-      <h2><%= title %></h2>
-      <%= doc_output %>
+    <div class="row">
+      <div class="three columns" style="padding: 20px 0">
+        <h5>Navigation</h5>
+        <% nav_parts.each do |part| %>
+          <%= part %>
+        <% end %>
+      </div>
+      <div class="nine columns" style="padding: 20px 0">
+        <h2><%= title %></h2>
+        <%= doc_output %>
+      </div>
     </div>
   </div>
 </body>

data/templates/nav.erb

@@ -0,0 +1,7 @@
+<ul>
+  <li><a href="<%= navdoc[:url] %>"><%= navdoc[:title] %></a>
+  <ul><% navdoc[:parts].each do |part| %>
+    <li><a href="<%= part[:url] %>"><%= part[:title] %></a></li>
+  <% end %></ul>
+  </li>
+</ul>

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rain-doc
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Martin Brennan
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-12-17 00:00:00.000000000 Z
+date: 2014-12-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -75,6 +75,7 @@ files:
 - templates/css/skeleton.css
 - templates/doc.erb
 - templates/layout.erb
+- templates/nav.erb
 homepage: http://martin-brennan.github.io/rain/
 licenses:
 - MIT