rain-doc 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2b22db23b6df6052719672b4f3e162ad0f38cd9b
+  data.tar.gz: 54b6d0d5844aece4dacebf9c72a94bad783287b4
+SHA512:
+  metadata.gz: eb235ac38baa2fd3e2f916f0760a4417cecebecfab38f85ea5b17d85bcb382c07dd18df08de0f0af04dc3e77bf3867c1f3541537e1620440578f1ec1b7fd530a
+  data.tar.gz: a9adc8daec64d905ced4275e71294b8332d47a669c2e50cdeb4911fc49291581683fa4a4bd1bc4c958d81212a56a14799e18f8faa19794d8f7aa91464830cf10

data/bin/raindoc

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+path = __FILE__
+while File.symlink?(path)
+path = File.expand_path(File.readlink(path), File.dirname(path))
+end
+$:.unshift(File.join(File.dirname(File.expand_path(path)), '..', 'lib'))
+
+require 'doc'
+require 'rain'
+
+Rain::CLI.start(ARGV)

data/lib/doc.rb

@@ -0,0 +1,154 @@
+require_relative 'parser'
+require_relative 'doc_part'
+require 'logger'
+
+module Rain
+
+  # used each time a file needs to be parsed.
+  # contains all documentation parts in the file
+  # as well as functionality to read through file
+  # contents line-by-line.
+  class Doc
+    attr_accessor :parser, :type, :parts, :current_part, :lines, :title,
+            :file_name, :file_contents, :file_ext
+
+    @@open_response = nil
+    @@open_response_id = nil
+    @@open_param = nil
+    @@open_param_type = nil
+    @@open_param_default = nil
+    @@log_lines = false
+
+    # sets up the doc using the file name and contents
+    # as a basis.
+    def initialize(file_name, file_contents, log_lines = false)
+
+      # set up basic options and defaults
+      self.file_name = file_name
+      self.file_contents = file_contents
+      self.file_ext = File.extname(file_name)
+      self.parts = []
+      self.lines = 0
+      @@log_lines = log_lines
+
+      # set the doc type based on extension
+      case self.file_ext
+      when '.rb'
+        self.type = :RUBY
+      when '.md', '.txt', '.markdown', '.mdown'
+        self.type = :MARKDOWN
+      end
+
+      # set parser with file type
+      self.parser = Rain::Parser.new(self.type)
+
+      # set the default title to the proper-case file name
+      # without the extension and underscores/dashes
+      self.title = self.file_name.sub(self.file_ext, '')
+      self.title.gsub!(/_|-/, ' ')
+
+      # very simple proper-caser
+      self.title.gsub!(/\w+/) { |word| word.capitalize }
+    end
+
+    # adds the current part to the parts array
+    # then sets a new current part up. a part is just
+    # a completed DocPart from a section of comments.
+    # for markdown files there will only be one doc part.
+    def new_part
+      self.parts << self.current_part if !self.current_part.nil?
+      self.current_part = Rain::DocPart.new
+    end
+
+    # parses the file by looping through all of the lines.
+    # defers to parser functionality to figure out if the
+    # current line is a tag and needs to be parsed into
+    # the docpart.
+    def parse
+      self.new_part
+      self.file_contents.each_line do |line|
+
+        # parse the current line
+        result = self.parser.parse(line)
+
+        # if there is no documentation for the result,
+        # create a new part and then set the current part to nil.
+        if result.nil?
+          self.new_part
+          self.current_part = nil
+          next
+        else
+
+          # if new doc block is found with the current part == nil,
+          # create a new part
+          self.new_part if self.current_part.nil?
+        end
+        
+        # log the result if the logger is enabled
+        Logger.new(STDOUT).info(result) if @@log_lines
+
+        # figure out what to do based on the result type
+        case result[:tag]
+        when :title
+          self.title = result[:title]
+        when :route
+          self.current_part.set_route(result[:route])
+        when :method
+          self.current_part.set_method(result[:method])
+        when :response
+
+          # open the current response tag using the code as a key
+          if result[:open]
+            @@open_response = result[:code]
+            @@open_response_id = result[:id]
+          else
+            @@open_response = nil
+          end
+        when :param
+
+          # open the current param tag using the name as the key
+          if result[:open]
+            @@open_param = result[:name]
+            @@open_param_type = result[:type]
+            @@open_param_default = result[:default]
+          else
+            @@open_param = nil
+          end
+        when :doc
+
+          # figure out if the doc needs to be added to an
+          # open response or param tag
+          if !@@open_response.nil?
+            self.current_part.append_response(@@open_response.to_i, @@open_response_id, result[:text])
+          elsif !@@open_param.nil?
+            self.current_part.append_param(@@open_param, result[:text], @@open_param_type, @@open_param_default)
+          else
+            self.current_part.append_doc(result[:text])
+          end
+        end
+
+        self.lines += 1
+      end
+
+      # add the part and create a new one
+      self.new_part
+
+      # remove any empty parts (for ruby docs)
+      if self.type == :RUBY
+        self.parts = self.parts.select{ |part| part.route != "//" }
+      end
+    end
+
+    def to_hash
+      return {
+        file_name: self.file_name,
+        file_contents: self.file_contents,
+        file_ext: self.file_ext,
+        title: self.title,
+        lines: self.lines,
+        parts: self.parts.map { |part| part.to_hash },
+        type: self.type.to_s
+      }
+    end
+  end
+end

data/lib/doc_part.rb

@@ -0,0 +1,138 @@
+module Rain
+  class DocPart
+    attr_accessor :http_method, :responses, :route, :doc, :params, :headers
+
+    def initialize
+      self.responses = []
+      self.doc = []
+      self.route = '//'
+      self.params = []
+      self.headers = []
+    end
+
+    # add or append a response with the specified code
+    # and the line of text passed in
+    def append_response(code, id, text)
+
+      # check that the response code is a number
+      begin
+        code.to_i
+      rescue Exception => e
+        raise ArgumentError, 'You can only use integer codes for HTTP response examples.'
+      end
+
+      # try and find the current response and id in the array
+      current_response = self.responses.select { |resp| resp[:code] == code && resp[:id] == id }.first
+
+      # add to array if nil
+      if current_response.nil?
+        self.responses << {
+          code: code,
+          id: id,
+          text: [text]
+        }
+      else
+
+        # otherwise append to the current response
+        self.responses.each do |resp|
+          if resp[:code] == code && resp[:id] == id
+            resp[:text] << text
+          end
+        end
+      end
+    end
+
+    # gets a response part by code and id and
+    # joins the parts of the text
+    def get_response(code, id)
+      response = self.responses.select { |resp| resp[:code] == code && resp[:id] == id }.first
+
+      raise 'Response code and id reference does not exist.' if response.nil?
+
+      response[:text].join
+    end
+
+    # sets the http method for the
+    # documentation part
+    def set_method(method)
+
+      # capitalize and convert to a symbol if not already a symbol
+      method.upcase! if !method.kind_of? Symbol
+
+      # check if the http method is valid
+      valid_methods = [:GET, :PUT, :POST, :PATCH, :DELETE]
+      if !valid_methods.include?(method.to_sym)
+        raise ArgumentError, "HTTP method must be valid (#{valid_methods.join(', ')})"
+      end
+
+      self.http_method = method
+    end
+
+    # appends the text to the current documentation for the part
+    def append_doc(text)
+      self.doc << text
+    end
+
+    # joins all of the text in the doc property of
+    # the part with spaces
+    def get_doc
+      self.doc.join(' ')
+    end
+
+    # sets the current route for the doc part
+    def set_route(path)
+      self.route = path
+    end
+
+    # gets the current route for the doc part
+    def get_route
+      self.route
+    end
+
+    # adds a parameter with the specified type. also sets a
+    # default value if specified
+    def append_param(name, description, type, default = nil)
+      self.params << {
+        name: name,
+        text: description,
+        type: type,
+        default: default
+      }
+    end
+
+    # gets a parameter by name. will return nil if
+    # the parameter does not exist
+    def get_param(name)
+      self.params.select { |param| param[:name] == name }.first
+    end
+
+    # adds a http header with name and
+    # description of the header
+    def append_header(name, description)
+      self.headers << {
+        name: name,
+        text: description
+      }
+    end
+
+    # gets a header's description from the store
+    def get_header(name)
+      header = self.headers.select { |h| h[:name] == name }.first
+
+      return nil if header.nil?
+
+      return header[:text]
+    end
+
+    def to_hash
+      return {
+        route: self.route,
+        params: self.params,
+        headers: self.headers,
+        doc: self.doc,
+        responses: self.responses,
+        http_method: self.http_method
+      }
+    end
+  end
+end

data/lib/parser.rb

@@ -0,0 +1,158 @@
+module Rain
+  class Parser
+    attr_accessor :type, :current_line
+
+    @@title_regex = /{title (.*?)}/m
+    @@route_regex = /{route (.*?)}/m
+    @@response_regex = /{response (.*?) (.*?)}/m
+    @@param_regex = /{param (.*?) (.*?)}/m
+    @@param_regex_default = /{param (.*?) (.*?) (.*?)}/m
+    @@method_regex = /(GET|PUT|POST|DELETE|PATCH|HEAD)/
+
+    def initialize(type)
+      self.type = type
+    end
+
+    # 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)
+      # return nil if there is no # on the line for ruby.
+      return nil if self.type == :RUBY && !line.strip().start_with?('#')
+
+      # strip blanks and # from the current line
+      line = strip_current_line(line)
+
+      # convert blank lines to new lines
+      if line == ""
+        line = "\n"
+      end
+
+      # title tag
+      if is_title?(line)
+        return {
+          tag: :title,
+          title: extract_title(line)
+        }
+      end
+
+      # method tag
+      if is_method?(line)
+        return {
+          tag: :method,
+          method: extract_method(line)
+        }
+      end
+
+      # route tag
+      if is_route?(line)
+        return {
+          tag: :route,
+          route: extract_route(line)
+        }
+      end
+
+      # response tag. must determine whether to open the tag
+      # for extra docs or close it
+      if is_response?(line)
+        open = line.start_with?('{/response') ? false : true
+        return {
+          tag: :response,
+          code: extract_response_code(line),
+          open: open,
+          id: extract_response_id(line)
+        }
+      end
+
+      # param tag. must determine whether to open the tag
+      # for extra docs or close it
+      if is_param?(line)
+        open = line.start_with?('{/param') ? false : true
+        return {
+          tag: :param,
+          name: extract_param_name(line),
+          type: extract_param_type(line),
+          default: extract_param_default(line),
+          open: open
+        }
+      end
+
+      # return simple doc line if no tags fit
+      return {
+        tag: :doc,
+        text: line
+      }
+    end
+
+    # remove any extra spaces from the current line
+    # and remove the comma # at the start of the
+    # line if the parser is for a ruby file
+    def strip_current_line(line)
+      line.strip!
+
+      # check the current type and if ruby, remove the #
+      if self.type == :RUBY
+        line.sub!('#', '')
+        line.strip!
+      end
+
+      return line
+    end
+
+    def is_title?(line)
+      line.start_with? '{title'
+    end
+
+    def extract_title(line)
+      line[@@title_regex, 1]
+    end
+
+    def is_method?(line)
+      line.start_with? '{method'
+    end
+
+    def extract_method(line)
+      line[@@method_regex, 1]
+    end
+
+    def is_route?(line)
+      line.start_with? '{route'
+    end
+
+    def extract_route(line)
+      line[@@route_regex, 1]
+    end
+
+    def is_response?(line)
+      line.start_with?('{response') || line.start_with?('{/response')
+    end
+
+    def extract_response_code(line)
+      line[@@response_regex, 1]
+    end
+
+    def extract_response_id(line)
+      line[@@response_regex, 2]
+    end
+
+    def is_param?(line)
+      line.start_with?('{param') || line.start_with?('{/param')
+    end
+
+    def extract_param_name(line)
+      line[@@param_regex, 1]
+    end
+
+    def extract_param_type(line)
+      if line[@@param_regex_default, 2].nil?
+        return line[@@param_regex, 2]
+      end
+
+      return line[@@param_regex_default, 2]
+    end
+
+    def extract_param_default(line)
+      line[@@param_regex_default, 3]
+    end
+  end
+end

data/lib/rain.rb

@@ -0,0 +1,83 @@
+require 'thor'
+require 'erb'
+require 'ostruct'
+require 'fileutils'
+
+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"
+	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.parse
+
+			@@docs << @doc
+		end
+
+		print "\nBuilding html output... \n"
+		build_html
+	end
+
+	# define the ascii art for the help command
+	desc "help", "Shows rain help documentation"
+	def help
+		print "       _      \n"
+		print "     _( )_    \n"
+		print "   _(     )_  \n"
+		print "  (_________) \n"
+		print "    \\ \\ \\ \\ \n"
+		print "     \\ \\ \\ \\ \n"
+		print "              \n"
+		print "---- RAIN ----\n"
+		print "              \n"
+		print "basic usage:\n"
+		print "  rain generate file/**/*.rb\n"
+	end
+
+	no_commands do
+		def build_html
+
+			# delete the old output files and create the dir
+			FileUtils.rm_rf('./rain_out')
+			Dir.mkdir('./rain_out')
+			Dir.mkdir('./rain_out/css')
+
+			# copy the template css to the output dir
+			FileUtils.cp_r './templates/css/.', './rain_out/css'
+
+			# load the templates
+			layout_template = File.read('./templates/layout.erb')
+			doc_template = File.read('./templates/doc.erb')
+
+			# load the doc properties and parts into the doc template
+			@@docs.each do |doc|
+
+				# 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 })
+				html = ERB.new(layout_template).result(layout_os.instance_eval {binding})
+
+				# write the html to a file
+				output_html(doc, html)
+			end
+		end
+
+		def output_html(doc, html)
+			# replace file_name extenstions with .html
+			file_name = File.basename(doc.file_name, doc.file_ext) + '.html'
+
+			# write the output to the file
+			File.open("./rain_out/#{file_name}", 'w') { |file| file.write(html) }
+		end
+	end
+end

data/templates/doc.erb

@@ -0,0 +1,45 @@
+<!-- loop through all of the doc parts for the doc and render output -->
+<% parts.each do |part| %>
+
+  <!-- HTTP method and route (if both specified) -->
+  <% if !part[:route].nil? && !part[:http_method].nil? %>
+    <p><strong><%= part[:http_method] %></strong> <%= part[:route] %></p>
+  <% end %>
+
+  <!-- display all of the docs together for the part -->
+  <% part[:doc].each do |doc| %>
+    <p><%= doc %></p>
+  <% end %>
+
+  <!-- show all of the params in a table -->
+  <% if part[:params].length > 0 %>
+    <h4>Parameters</h4>
+    <table class="u-full-width">
+      <thead>
+        <tr>
+          <th>Name</th>
+          <th>Type</th>
+          <th>Default</th>
+          <th>Description</th>
+        </tr>
+      </thead>
+      <% part[:params].each do |param| %>
+        <tr>
+          <td><%= param[:name] %></td>
+          <td><%= param[:type] %></td>
+          <td><%= param[:default].nil? ? 'N/A' : param[:default] %></td>
+          <td><%= param[:text] %></td>
+        </tr>
+      <% end %>
+    </table>
+  <% end %>
+
+  <!-- show all of the responses with examples -->
+  <% if part[:responses].length > 0 %>
+    <h4>Response Examples</h4>
+    <% part[:responses].each do |response| %>
+      <p><strong><%= response[:code] %></strong> <%= response[:id].upcase %></p>
+      <pre><code><%= response[:text].join("\n") %></code></pre>
+    <% end %>
+  <% end %>
+<% end %>

data/templates/layout.erb

@@ -0,0 +1,15 @@
+<html>
+<head>
+  <title>Rain | <%= title %></title>
+  <link rel="stylesheet" type="text/css" href="css/normalize.css" />
+  <link rel="stylesheet" type="text/css" href="css/skeleton.css" />
+</head>
+<body>
+  <div class="container">
+    <div class="twelve columns" style="padding: 20px 0">
+      <h2><%= title %></h2>
+      <%= doc_output %>
+    </div>
+  </div>
+</body>
+</html>

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: rain-doc
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Martin Brennan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-12-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 4.5.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 4.5.0
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.19.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.19.1
+description: "The aim of rain is to generate beautiful API documentation from a ruby
+  comment syntax with markdown mixed in.  \n                   The documentation can
+  be inline in .rb files, or separate .md or .txt files for overall architecture documentation.
+  \                   Rain also allows a large amount of customization when it comes
+  to templating and appearance of the API documentation.                    Branding
+  and unity of documentation appearance is important and rain offers a simple ebr-based
+  template system."
+email: mjrbrennan@gmail.com
+executables:
+- raindoc
+extensions: []
+extra_rdoc_files: []
+files:
+- bin/raindoc
+- lib/doc.rb
+- lib/doc_part.rb
+- lib/parser.rb
+- lib/rain.rb
+- templates/doc.erb
+- templates/layout.erb
+homepage: http://martin-brennan.github.io/rain/
+licenses:
+- MIT
+metadata: {}
+post_install_message: Rain installed successfully! Run rain generate file/paths/*.rb
+  to get started.
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.2
+signing_key: 
+specification_version: 4
+summary: Rain is a gem to generate beautiful and customizable API documentation, inspired
+  by yard and rdoc.
+test_files: []