apipie-dsl 2.0.0

data/lib/apipie_dsl/routing.rb

@@ -0,0 +1,17 @@
+module ApipieDSL
+  module Routing
+    module MapperExtensions
+      def apipie_dsl(options = {})
+        namespace 'apipie_dsl', path: ApipieDSL.configuration.doc_base_url do
+          get 'apipie_dsl_checksum', to: 'apipie_dsls#apipie_dsl_checksum', format: 'json'
+          constraints(version: /[^\/]+/, section: /[^\/]+/, class: /[^\/]+/,
+                      method: /[^\/]+/) do
+            get(options.reverse_merge("(:version)/(:section)/(:class)/(:method)" => 'apipie_dsls#index', as: :apipie_dsl))
+          end
+        end
+      end
+    end
+  end
+end
+
+ActionDispatch::Routing::Mapper.send :include, ApipieDSL::Routing::MapperExtensions

data/lib/apipie_dsl/see_description.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module ApipieDSL
+  class SeeDescription
+    attr_reader :link, :description
+
+    def initialize(method, options = {})
+      @method = method
+      @link = options[:link]
+      @description = options[:desc] || options[:description]
+      @scope = options[:scope]
+    end
+
+    def docs
+      { link: link, url: see_url, description: description }
+    end
+
+    private
+
+    def see_url
+      method_description = if @scope
+        if @scope.is_a?(ApipieDSL::ClassDescription)
+          @scope.method_description(@method)
+        else
+          ApipieDSL.get_method_description(@scope.to_s, @method)
+        end
+      else
+        ApipieDSL.get_method_description(@method)
+      end
+      raise ArgumentError, "Method #{@method} referenced in 'see' does not exist." if method_description.nil?
+
+      method_description.doc_url(method_description.klass.sections.first)
+    end
+  end
+end

data/lib/apipie_dsl/static_dispatcher.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module ApipieDSL
+  class FileHandler
+    def initialize(root)
+      @root          = root.chomp('/')
+      @compiled_root = /^#{Regexp.escape(root)}/
+      @file_server   = ::Rack::File.new(@root)
+    end
+
+    def match?(path)
+      # Replace all null bytes
+      path = ::Rack::Utils.unescape(path || '').gsub(/\x0/, '')
+
+      full_path = path.empty? ? @root : File.join(@root, path)
+      paths = "#{full_path}#{ext}"
+
+      matches = Dir[paths]
+      match = matches.detect { |m| File.file?(m) }
+      if match
+        match.sub!(@compiled_root, '')
+        match
+      end
+    end
+
+    def call(env)
+      @file_server.call(env)
+    end
+
+    def ext
+      @ext ||= begin
+        ext = cache_extension
+        "{,#{ext},/index#{ext}}"
+      end
+    end
+
+    def cache_extension
+      if ::ActionController::Base.respond_to?(:default_static_extension)
+        ::ActionController::Base.default_static_extension
+      else
+        ::ActionController::Base.page_cache_extension
+      end
+
+    end
+  end
+
+  class StaticDispatcher
+    # Dispatches the static files. Similar to ActionDispatch::Static, but
+    # it supports different baseurl configurations
+    def initialize(app, path)
+      @app = app
+      @file_handler = ApipieDSL::FileHandler.new(path)
+    end
+
+    def call(env)
+      @baseurl ||= ApipieDSL.configuration.doc_base_url
+      case env['REQUEST_METHOD']
+      when 'GET', 'HEAD'
+        path = env['PATH_INFO'].sub("#{@baseurl}/","/apipie_dsl/").chomp('/')
+
+        if match = @file_handler.match?(path)
+          env["PATH_INFO"] = match
+          return @file_handler.call(env)
+        end
+      end
+
+      @app.call(env)
+    end
+  end
+end

data/lib/apipie_dsl/tag_list_description.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ApipieDSL
+  class TagListDescription
+    attr_reader :tags
+
+    def initialize(tags)
+      @tags = tags
+    end
+  end
+end

data/lib/apipie_dsl/tasks/apipie_dsl/cache.rake

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative '../../tasks_utils'
+
+namespace :apipie_dsl do
+  desc 'Generate cache to avoid production dependencies on markup languages'
+  task :cache, [:include_json] => :environment do |_task, args|
+    args.with_defaults(include_json: false)
+    include_json = %w[1 true].include?(args[:include_json])
+    time_start = Time.now
+    puts "#{time_start} | Started"
+    ApipieDSL::TasksUtils.with_loaded_documentation do
+      puts "#{Time.now} | Documents loaded..."
+      ([nil] + ApipieDSL.configuration.languages).each do |lang|
+        I18n.locale = lang || ApipieDSL.configuration.default_locale
+        puts "#{Time.now} | Processing docs for #{lang}"
+        cache_dir = ENV['OUT'] || ApipieDSL.configuration.cache_dir
+        file_base = File.join(cache_dir, ApipieDSL.configuration.doc_base_url)
+        subdir = File.basename(file_base)
+        ApipieDSL.available_versions.each do |version|
+          file_base_version = File.join(file_base, version)
+          ApipieDSL.configuration.sections.each do |section|
+            ApipieDSL.url_prefix = "../../#{subdir}"
+            doc = ApipieDSL.docs(version, nil, nil, lang, section)
+            doc[:docs][:link_extension] = "#{lang_ext(lang)}.html"
+            ApipieDSL::TasksUtils.generate_index_page(file_base_version, doc, include_json, true, lang, section)
+            ApipieDSL.url_prefix = "../../../#{subdir}"
+            section_out = "#{file_base_version}/#{section}"
+            ApipieDSL::TasksUtils.generate_class_pages(version, section_out, doc, include_json, lang, section)
+            ApipieDSL.url_prefix = "../../../../#{subdir}"
+            ApipieDSL::TasksUtils.generate_method_pages(version, section_out, doc, include_json, lang, section)
+          end
+          ApipieDSL.url_prefix = "../../#{subdir}"
+          doc = ApipieDSL.docs(version, nil, nil, lang)
+          doc[:docs][:link_extension] = "#{lang_ext(lang)}.html"
+          ApipieDSL::TasksUtils.generate_help_page(file_base_version, doc, true, lang)
+        end
+      end
+    end
+    time_end = Time.now
+    puts "#{time_end} | Finished in #{time_end - time_start}"
+  end
+end

data/lib/apipie_dsl/tasks/apipie_dsl/static.rake

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative '../../tasks_utils'
+
+namespace :apipie_dsl do
+  desc 'Generate static documentation'
+  if defined?(Rails)
+    task :static, [:version, :include_json] => :environment do |_task, args|
+      ApipieDSL::TasksUtils.with_loaded_documentation do
+        args.with_defaults(
+          version: ApipieDSL.configuration.default_version,
+          include_json: false
+        )
+        include_json = %w[1 true].include?(args[:include_json])
+        out = ENV['OUT'] || File.join(::Rails.root, ApipieDSL.configuration.doc_path, 'dsldoc')
+        subdir = File.basename(out)
+        ApipieDSL::TasksUtils.copy_jscss(out)
+        ApipieDSL.configuration.version_in_url = false
+        ([nil] + ApipieDSL.configuration.languages).each do |lang|
+          I18n.locale = lang || ApipieDSL.configuration.default_locale
+          ApipieDSL.url_prefix = "../#{subdir}"
+          doc = ApipieDSL.docs(args[:version], nil, nil, lang)
+          doc[:docs][:link_extension] = "#{lang_ext(lang)}.html"
+          ApipieDSL::TasksUtils.generate_one_page(out, doc, lang)
+          ApipieDSL::TasksUtils.generate_plain_page(out, doc, lang)
+          ApipieDSL.configuration.sections.each do |section|
+            ApipieDSL.url_prefix = "../#{subdir}"
+            doc = ApipieDSL.docs(args[:version], nil, nil, lang, section)
+            doc[:docs][:link_extension] = "#{lang_ext(lang)}.html"
+            ApipieDSL::TasksUtils.generate_index_page(out, doc, include_json, false, lang, section)
+            ApipieDSL.url_prefix = "../../#{subdir}"
+            section_out = "#{out}/#{section}"
+            ApipieDSL::TasksUtils.generate_class_pages(args[:version], section_out, doc, include_json, lang, section)
+            ApipieDSL.url_prefix = "../../../#{subdir}"
+            ApipieDSL::TasksUtils.generate_method_pages(args[:version], section_out, doc, include_json, lang, section)
+          end
+          ApipieDSL.url_prefix = "../#{subdir}"
+          ApipieDSL::TasksUtils.generate_help_page(out, doc, false, lang)
+        end
+      end
+    end
+  end
+end

data/lib/apipie_dsl/tasks/apipie_dsl/static_json.rake

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative '../../tasks_utils'
+
+namespace :apipie_dsl do
+  desc 'Generate static documentation json'
+  if defined?(Rails)
+    task static_json: :environment do |_task, args|
+      ApipieDSL::TasksUtils.with_loaded_documentation do
+        args.with_defaults(version: ApipieDSL.configuration.default_version)
+        out = ENV['OUT'] || File.join(::Rails.root, ApipieDSL.configuration.doc_path, 'dsldoc')
+        ([nil] + ApipieDSL.configuration.languages).each do |lang|
+          doc = ApipieDSL.docs(args[:version], nil, nil, lang)
+          ApipieDSL::TasksUtils.generate_json_page(out, doc, lang)
+        end
+      end
+    end
+  else
+    task :static_json do |_task, args|
+      ApipieDSL.reload_documentation
+      args.with_defaults(version: ApipieDSL.configuration.default_version)
+      out = ENV['OUT'] || File.join(Rake.original_dir, ApipieDSL.configuration.doc_path, 'dsldoc')
+      ([nil] + ApipieDSL.configuration.languages).each do |lang|
+        doc = ApipieDSL.docs(args[:version], nil, nil, lang)
+        ApipieDSL::TasksUtils.generate_json_page(out, doc, lang)
+      end
+    end
+  end
+end

data/lib/apipie_dsl/tasks_utils.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../../app/helpers/apipie_dsl_helper'
+
+module ApipieDSL
+  module TasksUtils
+    def self.generate_json_page(file_base, doc, lang = nil)
+      FileUtils.mkdir_p(file_base) unless File.exist?(file_base)
+
+      filename = "schema_apipie_dsl#{lang_ext(lang)}.json"
+      File.open("#{file_base}/#{filename}", 'w') { |file| file.write(JSON.pretty_generate(doc)) }
+    end
+
+    def self.renderer
+      return @renderer if @renderer
+
+      @renderer = if defined?(Rails)
+                    rails_renderer
+                  else
+                    simple_renderer
+                  end
+    end
+
+    def self.simple_renderer
+      raise NotImplementedError
+    end
+
+    def self.rails_renderer
+      base_paths = [File.expand_path('../../app/views/apipie_dsl/apipie_dsls', __dir__)]
+      base_paths.unshift("#{Rails.root}/app/views/apipie_dsl/apipie_dsls") if File.directory?("#{Rails.root}/app/views/apipie_dsl/apipie_dsls")
+
+      layouts_paths = [File.expand_path('../../app/views/layouts', __dir__)]
+      layouts_paths.unshift("#{Rails.root}/app/views/layouts") if File.directory?("#{Rails.root}/app/views/layouts/apipie_dsl")
+      paths = ActionView::PathSet.new(base_paths + layouts_paths)
+      r_renderer = ActionView::Base.new(ActionController::Base.append_view_path(paths), {})
+      r_renderer.singleton_class.send(:include, ::ApipieDslHelper)
+      r_renderer
+    end
+
+    def self.render_page(file_name, template, variables, layout = 'apipie_dsl')
+      File.open(file_name, 'w') do |f|
+        variables.each do |var, val|
+          renderer.instance_variable_set("@#{var}", val)
+        end
+        f.write(renderer.render(template: template.to_s,
+                                layout: (layout && "apipie_dsl/#{layout}")))
+      end
+    end
+
+    def self.generate_one_page(file_base, doc, lang = nil)
+      FileUtils.mkdir_p(File.dirname(file_base)) unless File.exist?(File.dirname(file_base))
+
+      render_page("#{file_base}/#{File.basename(file_base)}-onepage#{lang_ext(lang)}.html", 'static',
+                  doc: doc[:docs], language: lang,
+                  languages: ApipieDSL.configuration.languages)
+    end
+
+    def self.generate_plain_page(file_base, doc, lang = nil)
+      FileUtils.mkdir_p(File.dirname(file_base)) unless File.exist?(File.dirname(file_base))
+
+      render_page("#{file_base}/#{File.basename(file_base)}-plain#{lang_ext(lang)}.html", 'plain',
+                  { doc: doc[:docs], language: lang,
+                    languages: ApipieDSL.configuration.languages }, nil)
+    end
+
+    def self.generate_index_page(file_base, doc, include_json = false, show_versions = false, lang = nil, section = nil)
+      versions = show_versions && ApipieDSL.available_versions
+      section_file = "#{file_base}/#{section}"
+      FileUtils.mkdir_p(File.dirname(section_file)) unless File.exist?(File.dirname(section_file))
+      render_page("#{section_file}#{lang_ext(lang)}.html",
+      'index', doc: doc[:docs], versions: versions, language: lang,
+               languages: ApipieDSL.configuration.languages, section: section)
+      File.open("#{file_base}#{lang_ext(lang)}.json", 'w') { |f| f << doc.to_json } if include_json
+    end
+
+    def self.generate_class_pages(version, file_base, doc, include_json = false, lang = nil, section = nil)
+      doc[:docs][:classes].each do |class_name, class_desc|
+        next unless ApipieDslHelper.in_section?(section, class_name)
+
+        class_file_base = File.join(file_base, class_desc[:id])
+        FileUtils.mkdir_p(File.dirname(class_file_base)) unless File.exist?(File.dirname(class_file_base))
+
+        doc = ApipieDSL.docs(version, class_name, nil, lang)
+        doc[:docs][:link_extension] = (lang ? ".#{lang}.html" : '.html')
+        render_page("#{class_file_base}#{lang_ext(lang)}.html", 'class',
+                    doc: doc[:docs], klass: doc[:docs][:classes].first,
+                    language: lang, languages: ApipieDSL.configuration.languages)
+        File.open("#{class_file_base}#{lang_ext(lang)}.json", 'w') { |f| f << doc.to_json } if include_json
+      end
+    end
+
+    def self.generate_method_pages(version, file_base, doc, include_json = false, lang = nil, section = nil)
+      doc[:docs][:classes].each do |class_name, class_params|
+        next unless ApipieDslHelper.in_section?(section, class_name)
+
+        class_params[:methods].each do |method|
+          method_file_base = File.join(file_base, class_name.to_s, method[:name].to_s)
+          FileUtils.mkdir_p(File.dirname(method_file_base)) unless File.exist?(File.dirname(method_file_base))
+
+          doc = ApipieDSL.docs(version, class_name, method[:name], lang)
+          doc[:docs][:link_extension] = (lang ? ".#{lang}.html" : '.html')
+          render_page("#{method_file_base}#{lang_ext(lang)}.html", 'method',
+                      doc: doc[:docs], klass: doc[:docs][:classes].first,
+                      method: doc[:docs][:classes].first[:methods].first,
+                      language: lang, languages: ApipieDSL.configuration.languages)
+
+          File.open("#{method_file_base}#{lang_ext(lang)}.json", 'w') { |f| f << doc.to_json } if include_json
+        end
+      end
+    end
+
+    def self.generate_help_page(file_base, doc, show_versions = false, lang = nil)
+      versions = show_versions && ApipieDSL.available_versions
+      section_file = "#{file_base}/help"
+      FileUtils.mkdir_p(File.dirname(section_file)) unless File.exist?(File.dirname(section_file))
+      render_page("#{section_file}#{lang_ext(lang)}.html", 'custom_help',
+      doc: doc[:docs], versions: versions, language: lang,
+      languages: ApipieDSL.configuration.languages, section: 'help')
+    end
+
+    def self.lang_ext(lang = nil)
+      lang ? ".#{lang}" : ''
+    end
+
+    def self.copy_jscss(dest)
+      src = File.expand_path('../../app/public/apipie_dsl', __dir__)
+      FileUtils.mkdir_p dest
+      FileUtils.cp_r "#{src}/.", dest
+    end
+
+    def self.with_loaded_documentation
+      ApipieDSL.reload_documentation
+      yield
+    end
+  end
+end

data/lib/apipie_dsl/utils.rb

@@ -0,0 +1,83 @@
+# rubocop:disable Style/FrozenStringLiteralComment
+module ApipieDSL
+  module Utils
+    attr_accessor :url_prefix
+
+    def superclass_for(klass_or_module)
+      return klass_or_module.superclass if klass_or_module.respond_to?(:superclass)
+
+      parent_name = to_s.split('::')[-2]
+      return nil if parent_name.nil?
+
+      Module.const_get(parent_name)
+    end
+
+    def markup_to_html(text)
+      return '' if text.nil?
+
+      if ApipieDSL.configuration.markup.respond_to?(:to_html)
+        ApipieDSL.configuration.markup.to_html(text)
+      else
+        text
+      end
+    end
+
+    def request_script_name
+      Thread.current[:apipie_dsl_req_script_name] || ''
+    end
+
+    def request_script_name=(script_name)
+      Thread.current[:apipie_dsl_req_script_name] = script_name
+    end
+
+    def full_url(path)
+      unless @url_prefix
+        @url_prefix = request_script_name.to_s
+        @url_prefix << ApipieDSL.configuration.doc_base_url
+      end
+      path = path.sub(%r{^/}, '')
+      ret = "#{@url_prefix}/#{path}"
+      ret.insert(0, '/') unless ret =~ %r{\A[./]}
+      ret.sub!(%r{/*\Z}, '')
+      ret
+    end
+
+    def include_javascripts
+      %w[bundled/jquery.js
+         bundled/bootstrap-collapse.js
+         bundled/prettify.js
+         apipie_dsl.js ].map do |file|
+        "<script type='text/javascript' src='#{ApipieDSL.full_url("javascripts/#{file}")}'></script>"
+      end.join("\n").html_safe
+    end
+
+    def include_stylesheets
+      %w[bundled/bootstrap.min.css
+         bundled/prettify.css
+         bundled/bootstrap-responsive.min.css ].map do |file|
+        "<link type='text/css' rel='stylesheet' href='#{ApipieDSL.full_url("stylesheets/#{file}")}'/>"
+      end.join("\n").html_safe
+    end
+  end
+end
+if RUBY_VERSION < '2.5.0'
+  class Hash
+    def transform_keys
+      result = {}
+      each do |key, value|
+        new_key = yield key
+        result[new_key] = value
+      end
+      result
+    end
+  end
+end
+if defined? Rails
+  class Module
+    # https://github.com/rails/rails/pull/35035
+    def as_json(options = nil)
+      name
+    end
+  end
+end
+# rubocop:enable Style/FrozenStringLiteralComment