apipie-dsl 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a35887dd905400d990949adfb5bd0322929bb06805e6355b4e03ab0d2ca4c816
-  data.tar.gz: c8a848d353d9041504d5e973486e2e1555eb75ded948e050c27e5d5f13948fe3
+  metadata.gz: 39b5db0089370b09f1623c2d6a5f5e5ae52206031528c9165d0005fb00ea66df
+  data.tar.gz: 0015e6d6757ede541f2f99448772c925bc4ad11627f288e2136328a80107ae2a
 SHA512:
-  metadata.gz: e0b1c8416e26e9ee2c132a769354a33786cdc4bc7785d6779b58b5793f040b38487e3887d00f6897cfe22f7b68c5f56697a3fa26a2ba5611217f35edfdf78786
-  data.tar.gz: 7870fee3fde011346710c7e3bd9da7124b0eeda34439cd373f81c2424a3ebfed6c25863297f5cab402b46a05285865314f43e97ad6a61d6ca9605e728fc3de8a
+  metadata.gz: f4742f04c2e4203df15840eba132d5b92c92b8fec197cbdf4d09d004d00ddaedbb7c9abcccfcff634cdaf6ae80b36c7a24cd9ea0847a4f7872e908601d4a82e6
+  data.tar.gz: 251cc977b4b6a6e5876c5650b7c57ce08410e8ad8a92a1d01a66f0ab7101f3607cd99f0793a05cc6656b979167ad05f32a512b9a4f3e064435f1689d1e244451

data/README.md

@@ -4,7 +4,7 @@ Apipie-dsl is a DSL for documenting DSLs written in Ruby. Instead of traditional
 use of `#comments`, ApipieDSL lets you describe the code, through the code.
 
 ## Getting started
-
+#### Within Rails application
 The easiest way to get ApipieDSL up and running with your app is:
 
 ```sh
@@ -25,6 +25,36 @@ Now you can start documenting your DSLs (see
   end
 ```
 
+#### Within plain Ruby application
+```sh
+  echo "gem 'apipie-dsl'" >> Gemfile
+  # To be able to generate HTML documentation via rake command
+  echo "gem 'rake'" >> Gemfile
+  echo "gem 'actionview'" >> Gemfile
+  bundle install
+```
+In case if you want to generate HTML documentation via rake command, I'd suggest
+have the following in your `Rakefile`:
+```ruby
+require 'apipie-dsl'
+
+# Configuration is required!
+ApipieDSL.configure do |config|
+  config.app_name = 'My DSL Docs'
+  # Matchers are needed to load your code with documentation
+  config.dsl_classes_matchers = [
+    "#{File.dirname(__dir__)}/dsl_example/common_classes.rb",
+    "#{File.dirname(__dir__)}/dsl_example/dsl.rb"
+  ]
+  # This is important for plain ruby application!
+  config.rails = false
+  # ... other configurations
+end
+spec = Gem::Specification.find_by_name('apipie-dsl')
+rakefile = "#{spec.gem_dir}/lib/apipie_dsl/Rakefile"
+load(rakefile)
+```
+
 # Documentation
 ## Contents
   - [__Configuration Reference__](#Configuration-Reference)

data/app/helpers/apipie_dsl_helper.rb

@@ -3,6 +3,7 @@
 require 'apipie_dsl/tasks_utils'
 
 module ApipieDslHelper
+  require 'action_view' unless defined?(ActionView)
   include ActionView::Helpers::TagHelper
 
   def heading(title, level = 1)
@@ -57,7 +58,7 @@ module ApipieDslHelper
     # Try to convert to a constant in case of LazyValidator usage
     # Will raise const missing exception in case of wrong usage of the method
     if obj.is_a?(String)
-      obj = defined?(Rails) ? obj.constantize : obj.split('::').reduce(::Module, :const_get)
+      obj = ApipieDSL.configuration.rails? ? obj.constantize : obj.split('::').reduce(::Module, :const_get)
     end
     return obj.to_s unless [::Module, ::Class, ::Array].include?(obj.class)
 

data/app/views/apipie_dsl/apipie_dsls/custom_help.html.erb

@@ -1,10 +1,12 @@
-<ul class='breadcrumb'>
-  <% dsl_sections.each do |section| %>
-    <li><a href='<%= @doc[:doc_url] %><%= section_ext(section) %><%= @doc[:link_extension] %>'><%= t("apipie_dsl.#{section}") %></a></li>
-  <% end %>
-    <li class='active pull-right'>
-      <% section = 'help' %>
-      <a href='<%= @doc[:doc_url] %><%= section_ext(section) %><%= @doc[:link_extension] %>'><%= t("apipie_dsl.#{section}") %></a>
-    </li>
-</ul>
-<%= render_help %>
+<% if ApipieDSL.configuration.help_layout %>
+  <ul class='breadcrumb'>
+    <% dsl_sections.each do |section| %>
+      <li><a href='<%= @doc[:doc_url] %><%= section_ext(section) %><%= @doc[:link_extension] %>'><%= t("apipie_dsl.#{section}") %></a></li>
+    <% end %>
+      <li class='active pull-right'>
+        <% section = 'help' %>
+        <a href='<%= @doc[:doc_url] %><%= section_ext(section) %><%= @doc[:link_extension] %>'><%= t("apipie_dsl.#{section}") %></a>
+      </li>
+  </ul>
+  <%= render_help %>
+<% end %>

data/lib/apipie_dsl.rb

@@ -18,7 +18,7 @@ require 'apipie_dsl/validator'
 module ApipieDSL
   require 'fileutils'
   if defined?(Rails)
-    require 'apipie_dsl/railtie' 
+    require 'apipie_dsl/railtie'
     require 'apipie_dsl/routing'
   end
 

data/lib/apipie_dsl/application.rb

@@ -231,12 +231,12 @@ module ApipieDSL
       old_locale = locale
       reset_locale(ApipieDSL.configuration.default_locale)
 
-      rails_mark_classes_for_reload if defined?(Rails)
+      rails_mark_classes_for_reload if ApipieDSL.configuration.rails?
 
       dsl_classes_paths.each do |file|
         begin
           ApipieDSL.debug("Loading #{file}")
-          if defined?(Rails)
+          if ApipieDSL.configuration.rails?
             load_class_from_file(file)
           else
             load(file)

data/lib/apipie_dsl/configuration.rb

@@ -7,7 +7,7 @@ module ApipieDSL
                   :doc_path, :languages, :link_extension, :translate, :locale,
                   :default_locale, :class_full_names, :autoload_methods,
                   :dsl_classes_matcher, :sections, :authenticate, :authorize,
-                  :use_cache, :app_info, :help_layout
+                  :use_cache, :app_info, :help_layout, :rails
     attr_writer   :validate_value, :ignored, :reload_dsl, :default_section,
                   :dsl_classes_matchers, :cache_dir
 
@@ -15,9 +15,13 @@ module ApipieDSL
     alias_method :class_full_names?, :class_full_names
     alias_method :autoload_methods?, :autoload_methods
     alias_method :use_cache?, :use_cache
+    alias_method :rails?, :rails
 
     def cache_dir
-      @cache_dir ||= File.join(Rails.root, 'public', 'apipie-dsl-cache')
+      return @cache_dir if @cache_dir
+      raise ConfigurationError.new('Please specify cache_dir to be able to use caching.') unless rails?
+
+      @cache_dir = File.join(Rails.root, 'public', 'apipie-dsl-cache')
     end
 
     def validate_value
@@ -46,11 +50,11 @@ module ApipieDSL
     end
 
     def reload_dsl?
-      @reload_dsl = if defined? Rails
-                          Rails.env.development?
-                        else
-                          @reload_dsl
-                        end
+      @reload_dsl = if rails?
+                      Rails.env.development?
+                    else
+                      @reload_dsl
+                    end
       @reload_dsl && !dsl_classes_matchers.empty?
     end
 
@@ -63,7 +67,7 @@ module ApipieDSL
       @app_name = 'Another DOC'
       @app_info = {}
       @copyright = nil
-      @validate = :implicitly
+      @validate = false
       @validate_value = true
       @doc_base_url = '/apipie-dsl'
       @layout = 'apipie_dsl/apipie_dsl'
@@ -82,6 +86,7 @@ module ApipieDSL
       @dsl_classes_matchers = []
       @sections = ['all']
       @default_section = nil
+      @rails = true
     end
   end
 end

data/lib/apipie_dsl/errors.rb

@@ -65,4 +65,16 @@ module ApipieDSL
       "A 'returns' statement cannot be used more than once"
     end
   end
+
+  class ConfigurationError < Error
+    attr_reader :value
+
+    def initialize(value)
+      @value = value
+    end
+
+    def to_s
+      "Configuration error: #{@value}"
+    end
+  end
 end

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

@@ -4,40 +4,79 @@ 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|
+  if ApipieDSL.configuration.rails?
+    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, section)
+            doc = ApipieDSL.docs(version, nil, nil, lang)
             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)
+            ApipieDSL::TasksUtils.generate_help_page(file_base_version, doc, true, lang)
           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
+      time_end = Time.now
+      puts "#{time_end} | Finished in #{time_end - time_start}"
+    end
+  else
+    task :cache, [:include_json] 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
-    time_end = Time.now
-    puts "#{time_end} | Finished in #{time_end - time_start}"
   end
 end

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

@@ -4,7 +4,7 @@ require_relative '../../tasks_utils'
 
 namespace :apipie_dsl do
   desc 'Generate static documentation'
-  if defined?(Rails)
+  if ApipieDSL.configuration.rails?
     task :static, [:version, :include_json] => :environment do |_task, args|
       ApipieDSL::TasksUtils.with_loaded_documentation do
         args.with_defaults(
@@ -20,13 +20,48 @@ namespace :apipie_dsl do
           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"
+          doc[:docs][:link_extension] = "#{ApipieDSL::TasksUtils.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"
+            doc[:docs][:link_extension] = "#{ApipieDSL::TasksUtils.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
+  else
+    task :static, [:version, :include_json] 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(Rake.original_dir, 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] = "#{ApipieDSL::TasksUtils.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] = "#{ApipieDSL::TasksUtils.lang_ext(lang)}.html"
             ApipieDSL::TasksUtils.generate_index_page(out, doc, include_json, false, lang, section)
             ApipieDSL.url_prefix = "../../#{subdir}"
             section_out = "#{out}/#{section}"

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

@@ -4,7 +4,7 @@ require_relative '../../tasks_utils'
 
 namespace :apipie_dsl do
   desc 'Generate static documentation json'
-  if defined?(Rails)
+  if ApipieDSL.configuration.rails?
     task static_json: :environment do |_task, args|
       ApipieDSL::TasksUtils.with_loaded_documentation do
         args.with_defaults(version: ApipieDSL.configuration.default_version)

data/lib/apipie_dsl/tasks_utils.rb

@@ -15,27 +15,18 @@ module ApipieDSL
     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")
-
+      if ApipieDSL.configuration.rails?
+        base_paths.unshift("#{Rails.root}/app/views/apipie_dsl/apipie_dsls") if File.directory?("#{Rails.root}/app/views/apipie_dsl/apipie_dsls")
+      end
       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")
+      if ApipieDSL.configuration.rails?
+        layouts_paths.unshift("#{Rails.root}/app/views/layouts") if File.directory?("#{Rails.root}/app/views/layouts/apipie_dsl")
+      end
       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
+      @renderer = ActionView::Base.new(paths, {})
+      @renderer.singleton_class.send(:include, ::ApipieDslHelper)
+      @renderer
     end
 
     def self.render_page(file_name, template, variables, layout = 'apipie_dsl')

data/lib/apipie_dsl/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ApipieDSL
-  VERSION = '2.0.0'
+  VERSION = '2.1.0'
 end

metadata

@@ -1,31 +1,31 @@
 --- !ruby/object:Gem::Specification
 name: apipie-dsl
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Oleh Fedorenko
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-03-15 00:00:00.000000000 Z
+date: 2020-04-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: nokogiri
+  name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.10.4
-  type: :runtime
+        version: '0'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.10.4
+        version: '0'
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: json-schema
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -39,7 +39,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: json-schema
+  name: maruku
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -53,7 +53,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: maruku
+  name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -67,7 +67,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: minitest
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -81,7 +81,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: rdoc
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -95,7 +95,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rdoc
+  name: RedCloth
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -109,7 +109,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: RedCloth
+  name: actionview
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="