jekyll-ramler 0.0.6 → 0.0.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG +11 -0
- data/Gemfile.lock +1 -1
- data/README.md +38 -0
- data/jekyll-ramler.gemspec +1 -1
- data/lib/raml-generate.rb +6 -1
- data/spec/reference_page_generator_spec.rb +13 -4
- data/spec/spec_assets/raml/simple.raml +3 -1
- metadata +1 -1
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 0d668fb1022f6cb3700db26e4dd935fa746f63f9
|
4
|
+
data.tar.gz: 64a617df40cdd668a128867b2846ee32e058e510
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: fafd7d5467c72fbee707c63b9be5827a9c07d6ab263f4506ee2249552c6f95704a2bdc3a3cf6a7d2380a1e7b8e6b12f7318a9f57950e0693d36a3c3dcb2a8eef
|
7
|
+
data.tar.gz: b970d476f50ec64b0c15a0c86453ee7b50d1bf6190cafb61cf7581e4400e01edcc5b8cb9e5a59a2901362bcf9997081cffa71afaad42425696a3ac5094b709fd
|
data/CHANGELOG
CHANGED
@@ -3,6 +3,17 @@ CHANGELOG
|
|
3
3
|
|
4
4
|
This project does *not* adhere to Semantic Versioning
|
5
5
|
|
6
|
+
## 0.0.7 - 2015-02-25
|
7
|
+
|
8
|
+
### Added
|
9
|
+
|
10
|
+
- Documentation on features and configuration
|
11
|
+
|
12
|
+
### Fixed
|
13
|
+
|
14
|
+
- Descriptions in hashes of JSON Schema were not being transformed via
|
15
|
+
Markdown. This has been corrected.
|
16
|
+
|
6
17
|
## 0.0.6 - 2015-02-23
|
7
18
|
|
8
19
|
### Fixed
|
data/Gemfile.lock
CHANGED
data/README.md
CHANGED
@@ -7,6 +7,16 @@ jekyll-ramler
|
|
7
7
|
Generates Jekyll pages for overview, security, and resource documentation
|
8
8
|
specificed in a RAML file.
|
9
9
|
|
10
|
+
## Features
|
11
|
+
|
12
|
+
- Renders RAML into multi-page HTML views - one page per endpoint
|
13
|
+
- Supports rendering multiple RAML files into web pages
|
14
|
+
- Transforms description fields found in RAML via Markdown
|
15
|
+
- Auto-generation of JSON Schema based on existing formParamters of
|
16
|
+
application/x-www-form-urlencoded
|
17
|
+
- Generation of complete RAML and JSON representations of API descriptors
|
18
|
+
- Supports Raw and Table based displays of JSON Schema included in your RAMLs
|
19
|
+
- Automatic insertion of inherited JSON Schema (via `$ref` and `allOf`)
|
10
20
|
|
11
21
|
## Installation
|
12
22
|
|
@@ -93,6 +103,34 @@ Several options can be defined by your project's _config.yml:
|
|
93
103
|
Generated descriptor files will be placed in the web folder configured for a
|
94
104
|
given source file.
|
95
105
|
|
106
|
+
### Markdown no_intra_emphasis
|
107
|
+
|
108
|
+
All description values found in a RAML file are transformed via Markdown, which
|
109
|
+
allows underscores (_) to be used as deliminators for emphasis and bold
|
110
|
+
content. Default transformation behavior can lead to mis-transformed content,
|
111
|
+
especially for words that contain underscores, such as variable names. As such,
|
112
|
+
it is recommended that you use the no_intra_emphasis extension of your choosen
|
113
|
+
Markdown engine. This extension can be enabled for *Redcarpet* by adding the
|
114
|
+
following to your _config.yml:
|
115
|
+
|
116
|
+
```
|
117
|
+
markdown: redcarpet
|
118
|
+
redcarpet:
|
119
|
+
extensions: ["no_intra_emphasis"]
|
120
|
+
```
|
121
|
+
|
122
|
+
Refer to <http://jekyllrb.com/docs/configuration/#markdown-options> for more
|
123
|
+
information on the use of no_intra_emphasis in Jekyll.
|
124
|
+
|
125
|
+
## Markdown Descriptions
|
126
|
+
|
127
|
+
jekyll-ramler will transform any *description* value found in a RAML via
|
128
|
+
Markdown. This includes description values on endpoints, methods, security
|
129
|
+
schemas, and in formParameters items. *body* values of `documentation` entires
|
130
|
+
will also be transformed via Markdown.
|
131
|
+
|
132
|
+
Note that in order to use Markdown in the description of a formParameter item,
|
133
|
+
you will need to use the pipe syntax (|) to avoid a RAML validation error.
|
96
134
|
|
97
135
|
## JSON Schema Support
|
98
136
|
|
data/jekyll-ramler.gemspec
CHANGED
data/lib/raml-generate.rb
CHANGED
@@ -110,9 +110,14 @@ module Jekyll
|
|
110
110
|
schema_generator = Jekyll::RamlSchemaGenerator.new(site, resource['title'])
|
111
111
|
schema_generator.insert_schemas(resource['methods'])
|
112
112
|
|
113
|
+
# Support a better presentation of the schema
|
114
|
+
resource = add_schema_hashes(resource)
|
115
|
+
|
113
116
|
# Transform descriptions via Markdown
|
114
117
|
resource = transform_resource_descriptions(resource)
|
115
|
-
|
118
|
+
|
119
|
+
# Make all this available to Liquid templates
|
120
|
+
self.data['methods'] = resource['methods']
|
116
121
|
end
|
117
122
|
|
118
123
|
private
|
@@ -61,11 +61,20 @@ describe 'ReferencePageGenerator', fakefs:true do
|
|
61
61
|
expect(test_doc.data['body']).to match /<p>.*<\/p>\n\n<h1.*>.*<\/h1>\n\n<p>.*<\/p>/m
|
62
62
|
expect(test_doc.data['body']).to include "<strong>Hello</strong>"
|
63
63
|
|
64
|
-
|
65
|
-
|
66
|
-
|
67
|
-
|
64
|
+
test_resources = @site.pages.select {|p| p.data['title'].start_with?('/')}
|
65
|
+
test_resources.each do |resource|
|
66
|
+
test_post = resource.data['methods'].select {|r| r['method'] == 'post' }.first
|
67
|
+
test_post['body']['application/x-www-form-urlencoded']['formParameters'].each do |param|
|
68
|
+
expect(param[1]['description']).to match /<p>.*<\/p>/m
|
69
|
+
end
|
68
70
|
end
|
71
|
+
|
72
|
+
test_post = test_resources.select{ |p| p.data['title'] == '/test_resource'}.first.data['methods'].select {|r| r['method'] == 'post' }.first
|
73
|
+
foo_desc = test_post['body']['application/x-www-form-urlencoded']['formParameters']['foo']['description']
|
74
|
+
expect(foo_desc).to match /<strong>.*<\/strong>/m
|
75
|
+
|
76
|
+
schema_hash_foo_desc = test_post['body']['application/json']['schema_hash']['properties']['foo']['description']
|
77
|
+
expect(schema_hash_foo_desc).to match /<strong>.*<\/strong>/m
|
69
78
|
end
|
70
79
|
|
71
80
|
it 'inserts trait properties into resources that have traits' do
|
@@ -55,12 +55,14 @@ traits:
|
|
55
55
|
application/x-www-form-urlencoded:
|
56
56
|
formParameters:
|
57
57
|
foo:
|
58
|
-
description:
|
58
|
+
description: |
|
59
|
+
**Fooing**
|
59
60
|
type: string
|
60
61
|
example: Foo
|
61
62
|
bar:
|
62
63
|
description: A place to get a drink
|
63
64
|
type: string
|
65
|
+
application/json:
|
64
66
|
/nested_test_resource:
|
65
67
|
post:
|
66
68
|
description: An example of a nested resource
|