jekyll-ramler 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dc0e1f14109050ea1f296cc5ed5b3fb1ac100510
-  data.tar.gz: fdf5cee7e082ea0397f460233683b1b13aa5e034
+  metadata.gz: 0b51a16a272803f10915253d041eadd53213f8d4
+  data.tar.gz: eb6626d0d68f77c7faa78041428214d419a2e664
 SHA512:
-  metadata.gz: 54959f41e90effd0ab0af92512cc49780771e6bfb5cf204e5b725f81d24f70834396eff93c9f384ee49738cfd689eb0a34959e986ef36a6a6809476d36aa9a43
-  data.tar.gz: 4fe17f77d424cba1df92d33ce9ecb08d31179f25dfcdb03e3443f7aac569021897e50b7ce21c7d5783de3e54fad03dd7cdac006a076591eed616312faadfd87e
+  metadata.gz: d9c0d5900dc16eadbfe0119fca2a96b125835506d031fec593bcd8b1679be9b49f9f5dbd4771526d0571c7bd3a41febe782c43c04b32a5e4509cf96debd13048
+  data.tar.gz: b445707349317d6923584813ff834a430ea55d48c17106bc489515a9dad8063aadec4970a33eb8679299d30fa589bcd255e489d217f6023087c932a9a24660f9

data/.travis.yml

@@ -7,3 +7,6 @@ install:
   - npm install raml-cop
   - bundle install
 script: "bundle exec rspec"
+branches:
+  only:
+    - master

data/Gemfile

@@ -6,5 +6,6 @@ group :test, :development do
   gem 'fakefs', require: 'fakefs/safe'
   gem 'pry'
   gem 'rspec'
+  gem 'rspec-mocks'
   gem 'ruby_deep_clone'
 end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jekyll-ramler (0.0.1)
+    jekyll-ramler (0.0.2)
       jekyll
 
 GEM
@@ -100,4 +100,5 @@ DEPENDENCIES
   jekyll-ramler!
   pry
   rspec
+  rspec-mocks
   ruby_deep_clone

data/README.md

@@ -17,6 +17,83 @@ Node.js script, to actually parse a RAML file. Thus, you will need to install
 [Node.js](http://nodejs.org/), then perform `npm install raml-cop`.
 
 
+## Configuration
+
+Several options can be defined by your project's _config.yml:
+
+- **ramler_api_paths**
+
+  A nested mapping of the files that jekyll-ramler should read while generating
+  content and the web folders where that content should be placed. *Keys* are
+  the file system paths (relative to your project's root directory) of the
+  files to be read. *Values* are the web paths (relative to web root) to place
+  all content generated based on the read file into. Keys must end with a 
+  forward slash. If no value is provided, web root (/) is used.
+
+  Behavior is undefined for cases in which jekyll-ramler is configured to 
+  output generated content of multiple source files to the same web path.
+
+  If *ramler_api_paths* is not defined, jekyll-ramler will default to reading
+  `api.json` from your project's root and placing generated files into web 
+  root.
+
+  At this time, only JSON representations of RAML can be read.
+
+  Example:
+
+  ```
+    ramler_api_paths:
+      ramls/api_v1.json: /an_api/v1/
+      ramls/api_v2.json: /an_api/v2/
+      ramls/api_v3.json: /an_api/
+      ramls/api_v3.json: /an_api/v3/
+      experimental/foo.json: /unstable/
+      ramls/popular.json: /
+  ```
+
+- **ramler_generated_sub_dirs**
+
+  A nested map defining the web sub directories that jekyll-ramler will place
+  generated pages into. Can have three mappings:
+
+  - *resource* - web sub directory for resource pages. Defaults to `resource`.
+  - *overview* - web sub directory for overview pages. Defaults to `overview`.
+  - *security* - web sub directory for security pages. Defaults to `security`.
+
+  Example:
+
+  ```
+    ramler_generated_sub_dirs:
+      resource: resources_pages
+      overview: general_documentation
+      security: security_information
+  ```
+
+  The same value can be used in multiple mappings. For example, all three
+  mappings could be set to `documentation`.
+
+- **ramler_downloadable_descriptor_basenames**
+
+  A nested map defining the basename of the generated, downloadable descriptors
+  (RAML and JSON). Format is similar to `ramler_api_paths`, where the *keys*
+  are file system paths of files to be read, while *values* are the basenames 
+  to use for generated descriptors. For example:
+
+  ```
+    ramler_downloadable_descriptor_basenames:
+      ramls/api_v1.json: api_v1
+      experimental/foo.json:  unstable
+  ```
+
+  will lead to the creation of `api_v1.raml`, `api_v1.json`, `unstable.raml`,
+  and `unstable.json` downloadable files.
+
+  If a basename is not defined, `api` is used as a basename. 
+
+  Generated descriptor files will be placed in the web folder configured for a
+  given source file.
+
+
 ## JSON Schema Support
 
 jekyll-ramler includes a few features for JSON Schema.

data/jekyll-ramler.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name        = 'jekyll-ramler'
-  s.version     = '0.0.1'
+  s.version     = '0.0.2'
   s.date        = '2015-02-09'
   s.authors     = ['GovDelivery']
   s.email       = 'support@govdelivery.com'

data/lib/raml-generate.rb

@@ -17,10 +17,11 @@ module Jekyll
   end
 
   class GeneratedPage<Page
-    def initialize(site, base, dir, item, layout=nil)
+    def initialize(site, base, web_root, dir, item, layout=nil)
       @site = site
       @base = base
       @dir = dir.gsub(/{(\w*)}/, '--\1--').gsub(/\s/, '_')
+      @dir = File.join(web_root, @dir)
       @name = 'index.html'
       
       layout = get_layout(dir) if layout.nil?
@@ -57,14 +58,14 @@ module Jekyll
   end
 
   class SecuritySchemePage<GeneratedPage
-    def initialize(site, base, dir, securityScheme)
-        super(site, base, dir, securityScheme, layout=get_layout('resource', site))
+    def initialize(site, base, web_root, dir, securityScheme)
+        super(site, base, web_root, dir, securityScheme, layout=get_layout('resource', site))
     end
   end
 
   class DocumentationPage<GeneratedPage
-    def initialize(site, base, dir, documentation)
-      super(site, base, dir, documentation)
+    def initialize(site, base, web_root, dir, documentation)
+      super(site, base, web_root, dir, documentation)
 
       output = documentation['content']
       self.data['body'] = transform_md(output)
@@ -72,13 +73,13 @@ module Jekyll
   end
 
   class ResourcePage<GeneratedPage 
-    def initialize(site, base, dir, resource, traits, securitySchemes)
+    def initialize(site, base, web_root, dir, resource, traits, securitySchemes)
       # Sandbox our resource, and do nothing with child resources
       resource = resource.dup
       resource.delete('resources')
 
       resource['title'] = dir.sub('resource', '') if not resource.include?('title')
-      super(site, base, dir, resource)
+      super(site, base, web_root, dir, resource)
 
       # Add security data to the resource
       resource.fetch('methods', []).each do |method|
@@ -196,8 +197,16 @@ module Jekyll
     def generate(site)
       @site = site
 
-      raml_js_path = site.config.fetch('raml_json_file_path', 'api.json')
-      raml_js = File.open(raml_js_path).read
+      site.config.fetch('ramler_api_paths', {'api.json' => '/'}).each do |file_path, web_root|
+        web_root = '/' if web_root.nil? or web_root.empty?
+        raise 'raml_api_paths web paths must end with "/"' if web_root[-1] != '/'
+        generate_api_pages(file_path, web_root)
+      end
+    end
+
+    def generate_api_pages(raml_path, web_root)
+      @web_root = web_root 
+      raml_js = File.open(raml_path).read
       raml_hash = JSON.parse(raml_js)
 
       # BETTER THE DATASTRUCTURES!
@@ -221,26 +230,30 @@ module Jekyll
         generate_resource_pages(raml_hash['resources'])
       end
 
-      dir = Jekyll::get_dir('overview', @site.config) 
+      dir = Jekyll::get_dir('security', @site.config) 
       @securitySchemes.each do |scheme_name, scheme|
         scheme_dir = File.join(dir, scheme_name)
         scheme['title'] = scheme_name
-        @site.pages << SecuritySchemePage.new(@site, @site.source, scheme_dir, scheme) 
+        @site.pages << SecuritySchemePage.new(@site, @site.source, @web_root, scheme_dir, scheme) 
       end
 
+      dir = Jekyll::get_dir('overview', @site.config) 
       raml_hash.fetch('documentation', []).each do |documentation|
         documentation_dir = File.join(dir, documentation['title'])
-        @site.pages << DocumentationPage.new(@site, @site.source, documentation_dir, documentation)
+        @site.pages << DocumentationPage.new(@site, @site.source, @web_root, documentation_dir, documentation)
       end
 
-      # Allow users to download the RAML, which may be modified since it was read
-      raml_download_path = site.config.fetch('raml_download_path', 'api.raml').split('/')
-      raml_download_filename = raml_download_path.delete_at(-1)
-      raml_download_path = raml_download_path.join('/') + '/'
+      # Allow users to download descriptor as RAML and JSON, which may be modified since it was read
+      download_basename = @site.config.fetch('ramler_downloadable_descriptor_basenames', {}).fetch(raml_path, 'api') 
+      raml_download_filename = download_basename + '.raml'
+      json_download_filename = download_basename + '.json'
 
       raml_yaml = raml_hash.to_yaml
       raml_yaml.sub!('---', '#%RAML 0.8')
-      @site.static_files << RawFile.new(@site, @site.source, raml_download_path, raml_download_filename, raml_yaml)
+      @site.static_files << RawFile.new(@site, @site.source, @web_root, raml_download_filename, raml_yaml)
+
+      raml_json = JSON.pretty_generate(raml_hash)
+      @site.static_files << RawFile.new(@site, @site.source, @web_root, json_download_filename, raml_json) 
     end
 
     private
@@ -255,7 +268,7 @@ module Jekyll
         resources.each do |resource|
           resource_name = resource["relativeUri"]
           resource_dir = File.join(dir, resource_name)
-          @site.pages << ResourcePage.new(@site, @site.source, resource_dir, resource, @traits, @securitySchemes)
+          @site.pages << ResourcePage.new(@site, @site.source, @web_root, resource_dir, resource, @traits, @securitySchemes)
           if resource.has_key?('resources')
             generate_resource_pages(resource['resources'], resource_dir)
         end

data/lib/utils.rb

@@ -2,7 +2,7 @@ require 'json'
 
 module Jekyll
   def self.get_dir(page_type, config)
-    config.fetch('page_dirs', {}).fetch(page_type, page_type)
+    config.fetch('ramler_generated_sub_dirs', {}).fetch(page_type, page_type)
   end
 
   def self.sanatize_json_string(s)

data/spec/config_spec.rb

@@ -0,0 +1,145 @@
+require_relative './spec_helper.rb'
+
+describe 'ReferencePageGenerator', fakefs:true do
+
+  before(:each) do
+    @site = Jekyll::Site.new(Jekyll.configuration({
+      "skip_config_files" => true,
+      "json_schema_schema_uri" => "http://json-schema.org/draft-04/schema#",
+      "ramler_api_paths" => {
+        'api.json' => '',
+        'productA/api.json' => '/productA/',
+        'service.json' => '/'}
+    }))
+    @rpg = Jekyll::ReferencePageGenerator.new
+
+    FakeFS.activate!
+    Pry.config.history.should_save = false;
+    Pry.config.history.should_load = false;
+
+    FileUtils.mkdir_p('_layouts')
+    File.open('_layouts/default.html', 'w') { |f| f << "{{ content }}" }
+
+    File.open('api.json', 'w') do |f|
+      f << JSON.pretty_generate(load_simple_raml)
+    end
+
+    FileUtils.mkdir_p('productA')
+    File.open('productA/api.json', 'w') do |f|
+      f << JSON.pretty_generate(load_simple_raml)
+    end
+
+    File.open('service.json', 'w') do |f|
+      f << JSON.pretty_generate(load_simple_raml)
+    end
+  end
+
+  after(:each) do
+    FakeFS.deactivate!
+  end
+
+  context 'Configuration' do
+
+    it 'reads "api.json" if no ramler_api_paths is provided' do
+      @site.config.delete('ramler_api_paths')
+      expect(File).to receive(:open).with('api.json').and_return(StringIO.new(JSON.pretty_generate(load_simple_raml)))
+      @rpg.generate(@site)
+    end
+
+    it 'reads ramls listed in the ramler_api_paths configuration mapping' do
+      expect(File).to receive(:open).with('api.json').and_return(StringIO.new(JSON.pretty_generate(load_simple_raml)))
+      expect(File).to receive(:open).with('productA/api.json').and_return(StringIO.new(JSON.pretty_generate(load_simple_raml)))
+      expect(File).to receive(:open).with('service.json').and_return(StringIO.new(JSON.pretty_generate(load_simple_raml)))
+      @rpg.generate(@site)
+    end
+
+    it 'places generated content into folders based on the ramler_api_paths configuration mapping' do
+      # Relying on some default values in this test
+        
+      @site.config['ramler_api_paths'].delete('api.json')
+      @rpg.generate(@site)
+      @site.process
+
+      # Look for files generated from service.json
+      expect(File.file?('_site/api.raml')).to be true
+      expect(File.directory?('_site/resource')).to be true
+
+      # Look for files generated from 
+      expect(File.directory?('_site/productA')).to be true
+      expect(File.file?('_site/productA/api.raml')).to be true
+      expect(File.directory?('_site/productA/resource')).to be true
+    end
+
+    it 'defaults to web root for any unconfigured ramls' do
+      # Only generate content for api.json, which does not define a web root
+      @site.config['ramler_api_paths'].delete('/productA/api.json')
+      @site.config['ramler_api_paths'].delete('service.json')
+      @rpg.generate(@site)
+      @site.process
+
+      expect(File.file?('_site/api.raml')).to be true
+      expect(File.directory?('_site/resource')).to be true
+    end
+
+    it 'throws an error if ramler_api_paths includes a value without a trailing slash' do
+      @site.config['ramler_api_paths'].delete('/productA/api.json')
+      @site.config['ramler_api_paths'].delete('service.json')
+      @site.config['ramler_api_paths']['api.json'] = 'api/v1'
+      expect {@rpg.generate(@site)}.to raise_error 
+    end
+
+    it 'defaults to "resource", "overview", and "security" for generated folders' do
+      @site.config['ramler_api_paths'].delete('/productA/api.json')
+      @site.config['ramler_api_paths'].delete('service.json')
+      @rpg.generate(@site)
+      @site.process
+
+      expect(File.directory?('_site/resource')).to be true
+      expect(File.directory?('_site/overview')).to be true
+      expect(File.directory?('_site/security')).to be true
+    end
+
+    it 'places generated content into folders based on ramler_generated_sub_dirs configuration mapping' do
+      @site.config['ramler_generated_sub_dirs'] = {
+        'resource' => 'endpoints',
+        'overview' => 'info',
+        'security' => 'auth'
+      }
+      @rpg.generate(@site)
+      @site.process
+
+      expect(File.directory?('_site/endpoints')).to be true
+      expect(File.directory?('_site/info')).to be true
+      expect(File.directory?('_site/auth')).to be true
+
+      expect(File.directory?('_site/productA/endpoints')).to be true
+      expect(File.directory?('_site/productA/info')).to be true
+      expect(File.directory?('_site/productA/auth')).to be true
+    end
+
+    it 'names downloadable descriptors "api.raml" and "api.json" by default' do
+      @site.config['ramler_api_paths'].delete('service.json')
+      @rpg.generate(@site)
+      @site.process
+
+      expect(File.file?('_site/api.json')).to be true
+      expect(File.file?('_site/api.raml')).to be true
+      expect(File.file?('_site/productA/api.json')).to be true
+      expect(File.file?('_site/productA/api.raml')).to be true
+    end
+
+    it 'names downloadable descriptors based on ramler_downloadable_descriptor_basenames' do
+      @site.config['ramler_api_paths'].delete('service.json')
+      @site.config['ramler_downloadable_descriptor_basenames'] = {
+        'productA/api.json' => 'productA_api'
+      }
+      @rpg.generate(@site)
+      @site.process
+
+      expect(File.file?('_site/api.json')).to be true
+      expect(File.file?('_site/api.raml')).to be true
+      expect(File.file?('_site/productA/productA_api.json')).to be true
+      expect(File.file?('_site/productA/productA_api.raml')).to be true
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -3,6 +3,7 @@ require 'fakefs/spec_helpers'
 require 'jekyll'
 require 'pry'
 require 'rspec/expectations'
+require 'rspec/mocks'
 require_relative '../lib/jekyll-ramler.rb'
 
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-ramler
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - GovDelivery
@@ -40,6 +40,7 @@ files:
 - lib/jekyll-ramler.rb
 - lib/raml-generate.rb
 - lib/utils.rb
+- spec/config_spec.rb
 - spec/reference_page_generator_spec.rb
 - spec/spec_assets/json/schema/allOf_schema.schema.json
 - spec/spec_assets/json/schema/foo.include.schema.json