jekyll-ramler 0.0.6 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e8c8f7b9ff188f55b8e43ba97d0a9008adf597f9
-  data.tar.gz: 17a4cd41e1e904142dffa6b51a02a45d8d6edbb0
+  metadata.gz: 0d668fb1022f6cb3700db26e4dd935fa746f63f9
+  data.tar.gz: 64a617df40cdd668a128867b2846ee32e058e510
 SHA512:
-  metadata.gz: 986223e927a63c61221a9fb1f271fc2d90a7b57ff265c0b56261f8a0bafd64baa5a63da38336ebfb2b60cd739edecd7504f043406e5283ef52cf703ab59c3738
-  data.tar.gz: a9844a050da4c5aba6beac0299839bd15682b434989c08dad4e4fe71ceaeb85bda721d43eb61a9120e932c8cd2e0da6f9ef52baf33f825d9bb2fcc86e6bc0c9f
+  metadata.gz: fafd7d5467c72fbee707c63b9be5827a9c07d6ab263f4506ee2249552c6f95704a2bdc3a3cf6a7d2380a1e7b8e6b12f7318a9f57950e0693d36a3c3dcb2a8eef
+  data.tar.gz: b970d476f50ec64b0c15a0c86453ee7b50d1bf6190cafb61cf7581e4400e01edcc5b8cb9e5a59a2901362bcf9997081cffa71afaad42425696a3ac5094b709fd

data/CHANGELOG

@@ -3,6 +3,17 @@ CHANGELOG
 
 This project does *not* adhere to Semantic Versioning
 
+## 0.0.7 - 2015-02-25 
+
+### Added
+
+- Documentation on features and configuration
+
+### Fixed
+
+- Descriptions in hashes of JSON Schema were not being transformed via
+	Markdown. This has been corrected.
+
 ## 0.0.6 - 2015-02-23
 
 ### Fixed

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jekyll-ramler (0.0.6)
+    jekyll-ramler (0.0.7)
       jekyll
 
 GEM

data/README.md

@@ -7,6 +7,16 @@ jekyll-ramler
 Generates Jekyll pages for overview, security, and resource documentation 
 specificed in a RAML file.
 
+## Features
+
+- Renders RAML into multi-page HTML views - one page per endpoint
+- Supports rendering multiple RAML files into web pages
+- Transforms description fields found in RAML via Markdown
+- Auto-generation of JSON Schema based on existing formParamters of
+  application/x-www-form-urlencoded
+- Generation of complete RAML and JSON representations of API descriptors
+- Supports Raw and Table based displays of JSON Schema included in your RAMLs
+- Automatic insertion of inherited JSON Schema (via `$ref` and `allOf`)
 
 ## Installation
 
@@ -93,6 +103,34 @@ Several options can be defined by your project's _config.yml:
   Generated descriptor files will be placed in the web folder configured for a
   given source file.
 
+### Markdown no_intra_emphasis
+
+All description values found in a RAML file are transformed via Markdown, which
+allows underscores (_) to be used as deliminators for emphasis and bold 
+content. Default transformation behavior can lead to mis-transformed content, 
+especially for words that contain underscores, such as variable names. As such,
+it is recommended that you use the no_intra_emphasis extension of your choosen
+Markdown engine. This extension can be enabled for *Redcarpet* by adding the
+following to your _config.yml:
+
+```
+markdown: redcarpet
+redcarpet:
+  extensions: ["no_intra_emphasis"]
+```
+
+Refer to <http://jekyllrb.com/docs/configuration/#markdown-options> for more
+information on the use of no_intra_emphasis in Jekyll.
+
+## Markdown Descriptions
+
+jekyll-ramler will transform any *description* value found in a RAML via
+Markdown. This includes description values on endpoints, methods, security 
+schemas, and in formParameters items. *body* values of `documentation` entires
+will also be transformed via Markdown.
+
+Note that in order to use Markdown in the description of a formParameter item,
+you will need to use the pipe syntax (|) to avoid a RAML validation error.
 
 ## JSON Schema Support
 

data/jekyll-ramler.gemspec

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

data/lib/raml-generate.rb

@@ -110,9 +110,14 @@ module Jekyll
       schema_generator = Jekyll::RamlSchemaGenerator.new(site, resource['title'])
       schema_generator.insert_schemas(resource['methods'])
 
+      # Support a better presentation of the schema
+      resource = add_schema_hashes(resource) 
+
       # Transform descriptions via Markdown
       resource = transform_resource_descriptions(resource)
-      self.data['methods'] = add_schema_hashes(resource['methods'])
+
+      # Make all this available to Liquid templates
+      self.data['methods'] = resource['methods']
     end
 
     private

data/spec/reference_page_generator_spec.rb

@@ -61,11 +61,20 @@ describe 'ReferencePageGenerator', fakefs:true do
       expect(test_doc.data['body']).to match /<p>.*<\/p>\n\n<h1.*>.*<\/h1>\n\n<p>.*<\/p>/m
       expect(test_doc.data['body']).to include "<strong>Hello</strong>"
       
-      test_resource = @site.pages.select {|p| p.data['title'] == '/test_resource'}.first
-      test_post = test_resource.data['methods'].select {|r| r['method'] == 'post' }.first
-      test_post['body']['application/x-www-form-urlencoded']['formParameters'].each do |param|
-        expect(param[1]['description']).to match /<p>.*<\/p>/m
+      test_resources = @site.pages.select {|p| p.data['title'].start_with?('/')}
+      test_resources.each do |resource|
+        test_post = resource.data['methods'].select {|r| r['method'] == 'post' }.first
+        test_post['body']['application/x-www-form-urlencoded']['formParameters'].each do |param|
+          expect(param[1]['description']).to match /<p>.*<\/p>/m
+        end
       end
+
+      test_post = test_resources.select{ |p| p.data['title'] == '/test_resource'}.first.data['methods'].select {|r| r['method'] == 'post' }.first
+      foo_desc = test_post['body']['application/x-www-form-urlencoded']['formParameters']['foo']['description']
+      expect(foo_desc).to match /<strong>.*<\/strong>/m
+
+      schema_hash_foo_desc = test_post['body']['application/json']['schema_hash']['properties']['foo']['description']
+      expect(schema_hash_foo_desc).to match /<strong>.*<\/strong>/m
     end
 
     it 'inserts trait properties into resources that have traits' do

data/spec/spec_assets/raml/simple.raml

@@ -55,12 +55,14 @@ traits:
       application/x-www-form-urlencoded:
         formParameters:
           foo:
-            description: Fooing
+            description: |
+              **Fooing**
             type: string
             example:  Foo
           bar:
             description: A place to get a drink
             type: string 
+      application/json:
   /nested_test_resource:
     post:
       description: An example of a nested resource

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-ramler
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.7
 platform: ruby
 authors:
 - GovDelivery