spectacle 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b42ae059b23d5ff986e540814af430c8caaa0626
-  data.tar.gz: aa149c1772cdfe1d28e949a1d2db6e660e77450c
+  metadata.gz: d8645f5fab30045d8686a7f8b69f0a1f7a4eab05
+  data.tar.gz: 478971030bbed4d15d6ec750b9d30c4fd61be65f
 SHA512:
-  metadata.gz: 36053c1424daf39030a9ada1ebb67615153c5bc998f762119dd0719ba1e95a91f8ec5fda7d230d07a8c72029807a6311415c74b33e451f0d56961876f4bc7267
-  data.tar.gz: 08a660ac60c8932c97bdce2566e573b773f7f94a62481f3eeed7a78396ace18404b210a58b1a6eb84b356bf865ebe0a942231ba7d702c6923e3bf541a5f1ab18
+  metadata.gz: 7ad38f4006eb10b8a169d6596c1cb2c040e9b6ca29c55332e34bef41f201d4ad4bb1d4443e6305aeb062cbf69cb74dbf72f7694afb33bd6c509b4e990652dce5
+  data.tar.gz: eefa8e706a0aaa847642fdbd913efd0299f7cc9d46ccdd1b8e1e953a779d3af8a04b2e51e4691c77a37f96ad1855e9308d69f8b17a0bd9419ee640993a132b98

data/.gitignore

@@ -20,3 +20,4 @@ bak
 node_modules
 app/views/*/*
 vendor/assets/*/*
+!vendor/assets/stylesheets/spectacle-core.scss

data/config/routes.rb

@@ -1,3 +1,3 @@
 Spectacle::Engine.routes.draw do
-  root 'apidocs#show'
+  # root 'apidocs#show'
 end

data/lib/spectacle.rb

@@ -1,5 +1,5 @@
 require "spectacle/config"
-require "spectacle/engine"
 require "spectacle/dsl"
 require "spectacle/task"
 require "spectacle/version"
+# require "spectacle/engine"

data/lib/spectacle/config.rb

@@ -1,79 +1,60 @@
 module Spectacle
   class Config
     class << self
-
-      def target_dir= value
-        @versions = value
+      attr_writer :spec_file
+      def spec_file
+        @spec_file || File.join(Rails.root, 'public/swagger.json')
       end
 
+      attr_writer :target_dir
       def target_dir
-        @target_dir ||= 'public/apidocs'
+        @target_dir || File.join(Rails.root, 'public/v1/docs')
       end
 
-      def spec_file= value
-        @spec_file = value
+      attr_writer :logo_file
+      def logo_file
+        @logo_file || nil
       end
 
-      def spec_file
-        @spec_file ||= 'public/swagger.json'
+      attr_writer :embedded_mode
+      def embedded_mode
+        @embedded_mode || false
       end
 
+      # Get the Spectacle library directory
+      #
+      # @return path
+      #
+      attr_writer :spectacle_lib_dir
+      def spectacle_lib_dir
+        return @spectacle_lib_dir if @spectacle_lib_dir
+        if Gem.win_platform?
+          File.join(node_prefix, 'node_modules', 'spectacle-docs')
+        else
+          File.join(node_prefix, 'lib', 'node_modules', 'spectacle-docs')
+        end
+      end
 
-      # @@base_api_controller = nil
-      #
-      # def base_api_controller
-      #   @@base_api_controller || ActionController::Base
-      # end
-      #
-      # def base_api_controllers
-      #   Array(base_api_controller)
-      # end
-      #
-      # def base_api_controller=(controller)
-      #   @@base_api_controller = controller
-      # end
-      #
-      # alias_method :base_api_controllers=, :base_api_controller=
-      #
-      # def base_applications
-      #   Array(base_application)
-      # end
-      #
-      # def base_application
-      #   Rails.application
-      # end
-      #
-      # def register_apis(versions)
-      #   base_api_controllers.each do |controller|
-      #     controller.send(:include, ImpotentMethods)
+      # # Get the Spectacle bin directory
+      # #
+      # # @return path
+      # #
+      # def spectacle_bin_path
+      #   return @spectacle_bin_path if @spectacle_bin_path
+      #   if Gem.win_platform?
+      #     File.join(node_prefix, 'bin', 'spectacle')
+      #   else
+      #     File.join(node_prefix, 'spectacle')
       #   end
-      #   @versions = versions
-      # end
-      #
-      # def registered_apis
-      #   @versions ||= {}
-      # end
-      #
-      # def transform_path(path, api_version)
-      #   # This is only for overriding, so don't perform any path transformations by default.
-      #   path
-      # end
-      #
-      # def log_exception
-      #   yield
-      #   rescue => e
-      #     write_log(:error, e)
-      #     raise
       # end
+
+      # Get the Node.js install prefix
       #
-      # def log_env_name
-      #   'SD_LOG_LEVEL'
-      # end
+      # @return path
       #
-      # def write_log(type, output)
-      #   $stderr.puts output if type == :error and ENV[log_env_name]=="1"
-      # end
-
+      def node_prefix
+        `npm config get prefix`.strip
+      end
     end
   end
 end

data/lib/spectacle/dsl.rb

@@ -1,335 +1,139 @@
-require 'open3'
-
 module Spectacle
   class DSL
-
-    DEFAULT_CONFIG = {
-      spectacle_dir: 'node_modules/spectacle-docs' #,
-      # target_dir: 'public/apidocs',
-      # spec_path: 'public/swagger.json'#,
-      # :base_path: '/',
-      # :clean_directory: false,
-      # :formatting: :pretty
-    }
-
     class << self
 
-      #
-      # Generate Spectacle static documentation
+      # Install Spectacle using `npm`
       #
       # @return success
       #
-      def generate
-        res = run "-C -e #{Config.spec_file}"
-        p res
-        if res[2]
-          source_dir = "#{DEFAULT_CONFIG[:spectacle_dir]}/app"
-          build_dir = "#{DEFAULT_CONFIG[:spectacle_dir]}/public"
-          views_dir = './app/views/spectacle'
-          assets_dir = './vendor/assets'
-
-          FileUtils.mkdir_p views_dir
-          FileUtils.mkdir_p "#{assets_dir}/stylesheets"
-          FileUtils.mkdir_p "#{assets_dir}/javascripts"
-
-          FileUtils.cp "#{build_dir}/index.html",
-                       "#{views_dir}/_docs.html.erb"
-          FileUtils.cp Dir.glob("#{source_dir}/stylesheets/*"),
-                       "#{assets_dir}/stylesheets"
-          # FileUtils.copy "#{build_dir}/stylesheets/spectacle.css",
-          #              "#{assets_dir}/stylesheets/spectacle.css"
-          FileUtils.cp "#{build_dir}/javascripts/spectacle.js",
-                       "#{assets_dir}/javascripts/spectacle.js"
-        end
-        res
+      def install
+        system 'npm install -g spectacle-docs'
       end
 
-      #
-      # Install Spectacle using `npm`
+      # Generate Spectacle documentation
       #
       # @return success
       #
-      def install
-        sh "npm install spectacle-docs"
+      def generate
+        spectacle arguments
       end
 
-      #
       # Run the Spectacle shell command
       #
       # @param args the command line arguments to pass to spectacle
       #
       # @return success
       #
-      def run args
-        sh "cd #{DEFAULT_CONFIG[:spectacle_dir]} && node bin/cli #{args}"
+      def spectacle args
+        # system "spectacle #{args}"
+        system "cd #{Config.spectacle_lib_dir} && node bin/spectacle-cli #{args}"
       end
 
+      # Generate Spectacle command line arguments
       #
-      # Identical to Open3.capture3, except that it rescues runtime errors
+      # @return string
       #
-      # @param env optional (as `Kernel.system')
-      # @param *cmd the command and its (auto-escaped) arguments
-      # @param opts optional a hash of options (as `Kernel.system')
+      def arguments
+        s = '' #'-C '
+        s += '-e ' if Config.embedded_mode
+        s += "-l #{Config.logo_file} " if Config.logo_file
+        s += Config.spec_file
+      end
+
+      # Replace paths in generated static documentation HTML
       #
-      # @return [stdout, stderr, success]
+      # @return success
       #
-      def sh(*cmd)
-        begin
-          stdout, stderr, status = Open3.capture3(*cmd)
-          [stdout, stderr, status.success?]
-        rescue
-          [$/, $/, nil]
+      def replace_static_asset_paths
+        if Config.target_dir.include?('/public/')
+          base_dir = Config.target_dir.match('/public(.*)')[1]
+          html_path = "#{Config.target_dir}/index.html"
+          contents = File.open(html_path, &:read)
+          contents.gsub!('/images', base_dir + '/images')
+          contents.gsub!('/stylesheets', base_dir + '/stylesheets')
+          contents.gsub!('/javascripts', base_dir + '/javascripts')
+          File.write(html_path, contents)
         end
       end
 
-      # def set_real_methods
-      #   # replace impotent methods with live ones
-      #   Config.base_api_controllers.each do |controller|
-      #     controller.send(:include, Methods)
-      #   end
-      # end
-      #
-      # def write_docs(apis = nil)
-      #   results = generate_docs(apis)
-      #   results.each{|api_version, result| write_doc(result) }
-      # end
+      # Copy generated static documentation HTML into the public folder
       #
-      # def write_doc(result)
-      #   settings = result[:settings]
-      #   config = result[:config]
-      #   create_output_paths(settings[:api_file_path])
-      #   clean_output_paths(settings[:api_file_path]) if config[:clean_directory] || false
-      #   root = result[:root]
-      #   resources = root.delete 'resources'
-      #   root.merge!(config[:attributes] || {}) # merge custom user attributes like info
-      #   # write the api-docs file
-      #   write_to_file('#{settings[:api_file_path]}/#{config[:api_file_name]}', root, config)
-      #   # write the individual resource files
-      #   resources.each do |resource|
-      #     resource_file_path = resource.delete 'resourceFilePath'
-      #     write_to_file(File.join(settings[:api_file_path], '#{resource_file_path}.json'), resource, config)
-      #   end
-      #   result
-      # end
-      #
-      # def generate_docs(apis=nil)
-      #   apis ||= Config.registered_apis
-      #   results = {}
-      #   set_real_methods
-      #
-      #   apis[DEFAULT_VER] = DEFAULT_CONFIG if apis.empty?
-      #
-      #   apis.each do |api_version, config|
-      #     settings = get_settings(api_version, config)
-      #     config.reverse_merge!(DEFAULT_CONFIG)
-      #     results[api_version] = generate_doc(api_version, settings, config)
-      #     results[api_version][:settings] = settings
-      #     results[api_version][:config] = config
-      #   end
-      #   results
-      # end
-      #
-      # def generate_doc(api_version, settings, config)
-      #   root = {
-      #     'apiVersion': api_version,
-      #     'swaggerVersion': '1.2',
-      #     'basePath': settings[:base_path],
-      #     :apis: [],
-      #     :authorizations: settings[:authorizations]
-      #   }
-      #   results = {:processed: [], :skipped: []}
-      #   resources = []
-      #
-      #   get_route_paths(settings[:controller_base_path]).each do |path|
-      #     ret = process_path(path, root, config, settings)
-      #     results[ret[:action]] << ret
-      #     if ret[:action] == :processed
-      #       resources << generate_resource(ret[:path], ret[:apis], ret[:models], settings, root, config, ret[:klass].swagger_config)
-      #       debased_path = get_debased_path(ret[:path], settings[:controller_base_path])
-      #       resource_api = {
-      #         path: '/#{Config.transform_path(trim_leading_slash(debased_path), api_version)}.{format}',
-      #         description: ret[:klass].swagger_config[:description]
-      #       }
-      #       root[:apis] << resource_api
-      #     end
-      #   end
-      #   root['resources'] = resources
-      #   results[:root] = root
-      #   results
-      # end
-      #
-      # private
-      #
-      # def transform_spec_to_api_path(spec, controller_base_path, extension)
-      #   api_path = spec.to_s.dup
-      #   api_path.gsub!('(.:format)', extension ? '.#{extension}' : '')
-      #   api_path.gsub!(/:(\w+)/, '{\1}')
-      #   api_path.gsub!(controller_base_path, '')
-      #   '/' + trim_slashes(api_path)
-      # end
-      #
-      # def camelize_keys_deep!(h)
-      #   h.keys.each do |k|
-      #     ks    = k.to_s.camelize(:lower)
-      #     h[ks] = h.delete k
-      #     camelize_keys_deep! h[ks] if h[ks].kind_of? Hash
-      #     if h[ks].kind_of? Array
-      #       h[ks].each do |a|
-      #         next unless a.kind_of? Hash
-      #         camelize_keys_deep! a
-      #       end
-      #     end
-      #   end
-      # end
-      #
-      # def trim_leading_slash(str)
-      #   return str if !str
-      #   str.gsub(/\A\/+/, '')
-      # end
-      #
-      # def trim_trailing_slash(str)
-      #   return str if !str
-      #   str.gsub(/\/+\z/, '')
-      # end
-      #
-      # def trim_slashes(str)
-      #   trim_leading_slash(trim_trailing_slash(str))
-      # end
-      #
-      # def get_debased_path(path, controller_base_path)
-      #   path.gsub('#{controller_base_path}', '')
-      # end
-      #
-      # def process_path(path, root, config, settings)
-      #   return {action: :skipped, reason: :empty_path} if path.empty?
-      #   klass = Config.log_exception { '#{path.to_s.camelize}Controller'.constantize } rescue nil
-      #   return {action: :skipped, path: path, reason: :klass_not_present} if !klass
-      #   return {action: :skipped, path: path, reason: :not_swagger_resource} if !klass.methods.include?(:swagger_config) or !klass.swagger_config[:controller]
-      #   return {action: :skipped, path: path, reason: :not_kind_of_parent_controller} if config[:parent_controller] && !(klass < config[:parent_controller])
-      #   apis, models, defined_nicknames = [], {}, []
-      #   routes.select{|i| i.defaults[:controller] == path}.each do |route|
-      #     unless nickname_defined?(defined_nicknames, path, route) # only add once for each route once e.g. PATCH, PUT
-      #       ret = get_route_path_apis(path, route, klass, settings, config)
-      #       apis = apis + ret[:apis]
-      #       models.merge!(ret[:models])
-      #       defined_nicknames << ret[:nickname] if ret[:nickname].present?
-      #     end
-      #   end
-      #   {action: :processed, path: path, apis: apis, models: models, klass: klass}
-      # end
-      #
-      # def route_verbs(route)
-      #   if defined?(route.verb.source) then route.verb.source.to_s.delete('$'+'^').split('|') else [route.verb] end.collect{|verb| verb.downcase.to_sym}
-      # end
-      #
-      # def path_route_nickname(path, route)
-      #   action = route.defaults[:action]
-      #   '#{path.camelize}##{action}'
-      # end
-      #
-      # def nickname_defined?(defined_nicknames, path, route)
-      #   target_nickname = path_route_nickname(path, route)
-      #   defined_nicknames.each{|nickname| return true if nickname == target_nickname }
-      #   false
-      # end
-      #
-      # def generate_resource(path, apis, models, settings, root, config, swagger_config)
-      #   metadata = ApiDeclarationFileMetadata.new(
-      #     root['apiVersion'], path, root['basePath'],
-      #     settings[:controller_base_path],
-      #     camelize_model_properties: config.fetch(:camelize_model_properties, true),
-      #     swagger_version: root['swaggerVersion'],
-      #     authorizations: root[:authorizations],
-      #     resource_path: swagger_config[:resource_path]
-      #   )
-      #   declaration = ApiDeclarationFile.new(metadata, apis, models)
-      #   declaration.generate_resource
-      # end
-      #
-      # def routes
-      #   Config.base_applications.map{|app| app.routes.routes.to_a }.flatten
-      # end
-      #
-      # def get_route_path_apis(path, route, klass, settings, config)
-      #   models, apis = {}, []
-      #   action = route.defaults[:action]
-      #   verbs = route_verbs(route)
-      #   return {apis: apis, models: models, nickname: nil} if !operation = klass.swagger_actions[action.to_sym]
-      #   operation = Hash[operation.map {|k, v| [k.to_s.gsub('@','').to_sym, v.respond_to?(:deep_dup) ? v.deep_dup : v.dup] }] # rename :@instance hash keys
-      #   nickname = operation[:nickname] = path_route_nickname(path, route)
-      #
-      #   route_path = if defined?(route.path.spec) then route.path.spec else route.path end
-      #   api_path = transform_spec_to_api_path(route_path, settings[:controller_base_path], config[:api_extension_type])
-      #   operation[:parameters] = filter_path_params(api_path, operation[:parameters]) if operation[:parameters]
-      #   operations = verbs.collect{|verb|
-      #     op = operation.dup
-      #     op[:method] = verb
-      #     op
-      #   }
-      #   apis << {:path: api_path, :operations: operations}
-      #   models = get_klass_models(klass)
-      #
-      #   {apis: apis, models: models, nickname: nickname}
-      # end
-      #
-      # def get_klass_models(klass)
-      #   models = {}
-      #   # Add any declared models to the root of the resource.
-      #   klass.swagger_models.each do |model_name, model|
-      #     formatted_model = {
-      #       id: model[:id],
-      #       required: model[:required],
-      #       properties: model[:properties],
-      #     }
-      #     formatted_model[:description] = model[:description] if model[:description]
-      #     models[model[:id]] = formatted_model
-      #   end
-      #   models
-      # end
-      #
-      # def get_settings(api_version, config)
-      #   base_path = trim_trailing_slash(config[:base_path] || '')
-      #   controller_base_path = trim_leading_slash(config[:controller_base_path] || '')
-      #   base_path += '/#{controller_base_path}' unless controller_base_path.empty?
-      #   api_file_path = config[:api_file_path]
-      #   authorizations = config[:authorizations]
-      #   settings = {
-      #     base_path: base_path,
-      #     controller_base_path: controller_base_path,
-      #     api_file_path: api_file_path,
-      #     authorizations: authorizations
-      #   }.freeze
-      # end
-      #
-      # def get_route_paths(controller_base_path)
-      #   paths = routes.map{|i| '#{i.defaults[:controller]}' }
-      #   paths.uniq.select{|i| i.start_with?(controller_base_path)}
-      # end
-      #
-      # def create_output_paths(api_file_path)
-      #   FileUtils.mkdir_p(api_file_path) # recursively create out output path
-      # end
-      #
-      # def clean_output_paths(api_file_path)
-      #   Dir.foreach(api_file_path) do |f|
-      #     fn = File.join(api_file_path, f)
-      #     File.delete(fn) if !File.directory?(fn) and File.extname(fn) == '.json'
-      #   end
-      # end
+      # @return success
       #
-      # def write_to_file(path, structure, config={})
-      #   content = case config[:formatting]
-      #     when :pretty; JSON.pretty_generate structure
-      #     else;         structure.to_json
-      #   end
-      #   FileUtils.mkdir_p File.dirname(path)
-      #   File.open(path, 'w') { |file| file.write content }
+      def copy_static
+        build_dir = "#{Config.spectacle_lib_dir}/public"
+
+        # Prepare the target folder
+        FileUtils.rm_rf Config.target_dir if File.exist?(Config.target_dir)
+        FileUtils.mkdir_p Config.target_dir
+
+        # Copy the SCSS files from the spectacle source tree to the
+        # assets folder
+        puts "Copying HTML from #{build_dir}/* to #{Config.target_dir}"
+        FileUtils.copy_entry build_dir, Config.target_dir
+
+        replace_static_asset_paths
+      end
+
+      # # Copy generated documentation HTML into the asset pipeline for dynamic
+      # # inclusion.
+      # #
+      # # @return success
+      # #
+      # def copy_dynamic
+      #   source_dir = "#{Config.spectacle_lib_dir}/app"
+      #   build_dir = "#{Config.spectacle_lib_dir}/public"
+      #
+      #   gem_dir = File.expand_path File.join(File.dirname(__FILE__), '../../')
+      #   views_dir = "#{gem_dir}/app/views/spectacle"
+      #   assets_dir = "#{gem_dir}/vendor/assets"
+      #
+      #   # Prepare the assets pipeline
+      #   FileUtils.mkdir_p views_dir
+      #   FileUtils.mkdir_p "#{assets_dir}/stylesheets"
+      #   FileUtils.mkdir_p "#{assets_dir}/javascripts"
+      #
+      #   # Copy compiled HTML to the views folder as a ERB partial.
+      #   # This way it can be included in any page.
+      #   puts "Copying HTML from #{build_dir}/index.html to #{views_dir}/_docs.html.erb"
+      #   FileUtils.cp "#{build_dir}/index.html",
+      #                "#{views_dir}/_docs.html.erb"
+      #
+      #   # Copy the SCSS files from the spectacle source tree to the
+      #   # assets folder
+      #   puts "Copying SCSS from #{source_dir}/stylesheets/* to #{assets_dir}/stylesheets"
+      #   FileUtils.cp Dir.glob("#{source_dir}/stylesheets/*"),
+      #                "#{assets_dir}/stylesheets"
+      #
+      #   # Copy the compiled CSS files. These can be used optionally instead
+      #   # of SCSS files if no configuration is required.
+      #   # FileUtils.cp "#{build_dir}/stylesheets/spectacle.css",
+      #   #              "#{assets_dir}/stylesheets/spectacle.css"
+      #   # FileUtils.cp "#{build_dir}/stylesheets/foundation.css",
+      #   #               "#{assets_dir}/stylesheets/foundation.css"
+      #
+      #   # Copy the compiled JS files to the assets folder
+      #   puts "Copying JS from #{build_dir}/javascripts/spectacle.js to #{assets_dir}/javascripts/spectacle.js"
+      #   FileUtils.cp "#{build_dir}/javascripts/spectacle.js",
+      #                "#{assets_dir}/javascripts/spectacle.js"
+      #
+      #   replace_static_asset_paths
       # end
-      #
-      # def filter_path_params(path, params)
-      #   params.reject do |param|
-      #     param_as_variable = '{#{param[:name]}}'
-      #     param[:param_type] == :path && !path.include?(param_as_variable)
+
+      # # Identical to Open3.capture3, except that it rescues runtime errors
+      # #
+      # # @param env optional (as `Kernel.system')
+      # # @param *cmd the command and its (auto-escaped) arguments
+      # # @param opts optional a hash of options (as `Kernel.system')
+      # #
+      # # @return [stdout, stderr, success]
+      # #
+      # def sh *cmd
+      #   begin
+      #     stdout, stderr, status = Open3.capture3(*cmd)
+      #     [stdout, stderr, status.success?]
+      #   rescue
+      #     [$/, $/, false]
       #   end
       # end
     end