doc_my_routes 0.9.0 → 0.10.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/etc/index.html.erb +2 -155
- data/etc/partial.html.erb +154 -0
- data/lib/doc_my_routes/doc/config.rb +18 -2
- data/lib/doc_my_routes/doc/documentation.rb +32 -4
- data/lib/doc_my_routes/version.rb +1 -1
- metadata +17 -2
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: c573d2ed3d69b19c86e42facf512dceae2c25c15
|
4
|
+
data.tar.gz: 8e2b17bd3e31ed83c44b589661f73fb863c3432b
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 59ecabbfa6abf47254ae0222a717c51c2a043651c623cf86974e41ff8d9ee0424d0e7937ce941a8a7824ce34e76ecfc3aebe3110e69ccf36e023212f9378b4d2
|
7
|
+
data.tar.gz: 118fc92f38f447ebcffe0db371e77bf920badf4c3601c66c00843e0f157670a95f6fbd71b9c0592fc69820c4e77c7d44ff592159d8a280a00407667bbc030460
|
data/etc/index.html.erb
CHANGED
@@ -2,163 +2,10 @@
|
|
2
2
|
<html lang="en">
|
3
3
|
<head>
|
4
4
|
<meta charset="utf-8">
|
5
|
-
<title><%=
|
5
|
+
<title><%= title %></title>
|
6
6
|
<link href='<%= DocMyRoutes.config.destination_css %>' rel='stylesheet' type='text/css'/>
|
7
7
|
</head>
|
8
8
|
<body>
|
9
|
-
|
10
|
-
<header>
|
11
|
-
<div id="api_info" class="info">
|
12
|
-
<div class="info_title"><%= data[:main][:info][:title] %></div>
|
13
|
-
<div class="info_description"><%= data[:main][:info][:description] %></div>
|
14
|
-
</div>
|
15
|
-
</header>
|
16
|
-
|
17
|
-
<section class="resources">
|
18
|
-
<%# API documentation content %>
|
19
|
-
<%
|
20
|
-
data[:main][:apis].each do |resource_name, operations|
|
21
|
-
%>
|
22
|
-
<article class="resource">
|
23
|
-
<details open>
|
24
|
-
<summary class="resource"><%= resource_name %></summary>
|
25
|
-
<%
|
26
|
-
operations.sort_by { |route| route[:http_method] }.each do |route|
|
27
|
-
verb = route[:http_method]
|
28
|
-
%>
|
29
|
-
<article class="operation <%= verb.downcase %>">
|
30
|
-
<details>
|
31
|
-
<summary class="operation">
|
32
|
-
<span class="http_method <%= verb.downcase %>">
|
33
|
-
<%= verb %><%= ' / HEAD' if verb == 'GET' %>
|
34
|
-
</span>
|
35
|
-
<span class="path <%= verb.downcase %>">
|
36
|
-
<%= route[:path]%>
|
37
|
-
</span>
|
38
|
-
<span class="summary <%= verb.downcase %>">
|
39
|
-
<%= route[:summary]%>
|
40
|
-
</span>
|
41
|
-
</summary>
|
42
|
-
<div class="content <%= verb.downcase %>">
|
43
|
-
<% unless route[:produces].empty? %>
|
44
|
-
<h4>Content Type</h4>
|
45
|
-
<p><%= route[:produces].join(', ') %></p>
|
46
|
-
<% end %>
|
47
|
-
|
48
|
-
<% if route[:notes] && !route[:notes].empty? %>
|
49
|
-
<h4>Implementation Notes</h4>
|
50
|
-
<p><%= route[:notes] %></p>
|
51
|
-
<% end %>
|
52
|
-
|
53
|
-
<%# List of , if present %>
|
54
|
-
<% if route[:parameters] && !route[:parameters].empty? %>
|
55
|
-
<table class="smallwidth">
|
56
|
-
<thead>
|
57
|
-
<tr>
|
58
|
-
<th>Parameter</th>
|
59
|
-
</tr>
|
60
|
-
</thead>
|
61
|
-
<tbody class="operation-params">
|
62
|
-
<% route[:parameters].each do |param| %>
|
63
|
-
<tr>
|
64
|
-
<td><%= param %></td>
|
65
|
-
</tr>
|
66
|
-
<% end %>
|
67
|
-
</tbody>
|
68
|
-
</table>
|
69
|
-
<% end %>
|
70
|
-
|
71
|
-
<%# List of possible response statuses %>
|
72
|
-
<h4>Response statuses</h4>
|
73
|
-
<table class="smallwidth">
|
74
|
-
<thead>
|
75
|
-
<tr>
|
76
|
-
<th class="status_code">HTTP Status Code</th>
|
77
|
-
<th class="status_code_message">Reason</th>
|
78
|
-
</tr>
|
79
|
-
</thead>
|
80
|
-
<tbody class="operation-status">
|
81
|
-
<% route[:status_codes].each do |status_code, description| %>
|
82
|
-
<tr>
|
83
|
-
<td class="status_code"><%= status_code %></td>
|
84
|
-
<td class="status_code_message"><%= description %></td>
|
85
|
-
</tr>
|
86
|
-
<% end %>
|
87
|
-
</tbody>
|
88
|
-
</table>
|
89
|
-
|
90
|
-
<%# Display examples, if present %>
|
91
|
-
<% if route[:examples] %>
|
92
|
-
<h4>Examples</h4>
|
93
|
-
<div>
|
94
|
-
<%# TODO: move this logic outside %>
|
95
|
-
<% route[:examples].each do |example| %>
|
96
|
-
<article class="example <%= verb.downcase %>">
|
97
|
-
<details>
|
98
|
-
<summary class="example <%= verb.downcase %>"><%= example['description'] %></summary>
|
99
|
-
<div class="example_content <%= verb.downcase %>">
|
100
|
-
<div class="request">
|
101
|
-
<h4>Request</h4>
|
102
|
-
<div class="code <%= verb.downcase %>">
|
103
|
-
<div>
|
104
|
-
<h5>Query</h5>
|
105
|
-
<pre class='request-code query'><code class="json"><%= example['request']['query'] %></code></pre>
|
106
|
-
</div>
|
107
|
-
|
108
|
-
<% if example['request']['headers'] %>
|
109
|
-
<div>
|
110
|
-
<h5>Headers</h5>
|
111
|
-
<% example['request']['headers'].each do |key, value| %>
|
112
|
-
<pre class="request-code headers"><code class="json"><%= key %>: <%= value %></code></pre>
|
113
|
-
<% end %>
|
114
|
-
</div>
|
115
|
-
<% end %>
|
116
|
-
|
117
|
-
<% if example['request']['body'] %>
|
118
|
-
<div>
|
119
|
-
<h5>Body</h5>
|
120
|
-
<pre class='request-code body'><code class="json"><%= example['request']['body'] %></code></pre>
|
121
|
-
</div>
|
122
|
-
<% end %>
|
123
|
-
</div>
|
124
|
-
</div>
|
125
|
-
|
126
|
-
<div class="response">
|
127
|
-
<h4>Response (status <%= example['response']['status'] %>)</h4>
|
128
|
-
<div class="code <%= verb.downcase %>">
|
129
|
-
<% if example['response']['headers'] %>
|
130
|
-
<div>
|
131
|
-
<h5>Headers</h5>
|
132
|
-
<% example['response']['headers'].each do |key, value| %>
|
133
|
-
<pre class="request-code headers"><code class="json"><%= key %>: <%= value %></code></pre>
|
134
|
-
<% end %>
|
135
|
-
</div>
|
136
|
-
<% end %>
|
137
|
-
|
138
|
-
<div>
|
139
|
-
<h5>Body</h5>
|
140
|
-
<% if example['response']['body'] %>
|
141
|
-
<pre class='request-code body'><code class="json"><%= example['response']['body'] %></code></pre>
|
142
|
-
<% else %>
|
143
|
-
<pre class='request-code body'><code class="json">No body</code></pre>
|
144
|
-
<% end %>
|
145
|
-
</div>
|
146
|
-
</div>
|
147
|
-
</div>
|
148
|
-
</div>
|
149
|
-
</details>
|
150
|
-
</article>
|
151
|
-
<% end %>
|
152
|
-
</div>
|
153
|
-
<% end %>
|
154
|
-
</div>
|
155
|
-
</details>
|
156
|
-
</article>
|
157
|
-
<% end %>
|
158
|
-
</details>
|
159
|
-
</article>
|
160
|
-
<% end %>
|
161
|
-
</section>
|
162
|
-
</section>
|
9
|
+
<%= body %>
|
163
10
|
</body>
|
164
11
|
</html>
|
@@ -0,0 +1,154 @@
|
|
1
|
+
<section class="documentation">
|
2
|
+
<header>
|
3
|
+
<div id="api_info" class="info">
|
4
|
+
<div class="info_title"><%= data[:main][:info][:title] %></div>
|
5
|
+
<div class="info_description"><%= data[:main][:info][:description] %></div>
|
6
|
+
</div>
|
7
|
+
</header>
|
8
|
+
|
9
|
+
<section class="resources">
|
10
|
+
<%# API documentation content %>
|
11
|
+
<%
|
12
|
+
data[:main][:apis].each do |resource_name, operations|
|
13
|
+
%>
|
14
|
+
<article class="resource">
|
15
|
+
<details open>
|
16
|
+
<summary class="resource"><%= resource_name %></summary>
|
17
|
+
<%
|
18
|
+
operations.sort_by { |route| route[:http_method] }.each do |route|
|
19
|
+
verb = route[:http_method]
|
20
|
+
%>
|
21
|
+
<article class="operation <%= verb.downcase %>">
|
22
|
+
<details>
|
23
|
+
<summary class="operation">
|
24
|
+
<span class="http_method <%= verb.downcase %>">
|
25
|
+
<%= verb %><%= ' / HEAD' if verb == 'GET' %>
|
26
|
+
</span>
|
27
|
+
<span class="path <%= verb.downcase %>">
|
28
|
+
<%= route[:path]%>
|
29
|
+
</span>
|
30
|
+
<span class="summary <%= verb.downcase %>">
|
31
|
+
<%= route[:summary]%>
|
32
|
+
</span>
|
33
|
+
</summary>
|
34
|
+
<div class="content <%= verb.downcase %>">
|
35
|
+
<% unless route[:produces].empty? %>
|
36
|
+
<h4>Content Type</h4>
|
37
|
+
<p><%= route[:produces].join(', ') %></p>
|
38
|
+
<% end %>
|
39
|
+
|
40
|
+
<% if route[:notes] && !route[:notes].empty? %>
|
41
|
+
<h4>Implementation Notes</h4>
|
42
|
+
<p><%= route[:notes] %></p>
|
43
|
+
<% end %>
|
44
|
+
|
45
|
+
<%# List of , if present %>
|
46
|
+
<% if route[:parameters] && !route[:parameters].empty? %>
|
47
|
+
<table class="smallwidth">
|
48
|
+
<thead>
|
49
|
+
<tr>
|
50
|
+
<th>Parameter</th>
|
51
|
+
</tr>
|
52
|
+
</thead>
|
53
|
+
<tbody class="operation-params">
|
54
|
+
<% route[:parameters].each do |param| %>
|
55
|
+
<tr>
|
56
|
+
<td><%= param %></td>
|
57
|
+
</tr>
|
58
|
+
<% end %>
|
59
|
+
</tbody>
|
60
|
+
</table>
|
61
|
+
<% end %>
|
62
|
+
|
63
|
+
<%# List of possible response statuses %>
|
64
|
+
<h4>Response statuses</h4>
|
65
|
+
<table class="smallwidth">
|
66
|
+
<thead>
|
67
|
+
<tr>
|
68
|
+
<th class="status_code">HTTP Status Code</th>
|
69
|
+
<th class="status_code_message">Reason</th>
|
70
|
+
</tr>
|
71
|
+
</thead>
|
72
|
+
<tbody class="operation-status">
|
73
|
+
<% route[:status_codes].each do |status_code, description| %>
|
74
|
+
<tr>
|
75
|
+
<td class="status_code"><%= status_code %></td>
|
76
|
+
<td class="status_code_message"><%= description %></td>
|
77
|
+
</tr>
|
78
|
+
<% end %>
|
79
|
+
</tbody>
|
80
|
+
</table>
|
81
|
+
|
82
|
+
<%# Display examples, if present %>
|
83
|
+
<% if route[:examples] %>
|
84
|
+
<h4>Examples</h4>
|
85
|
+
<div>
|
86
|
+
<%# TODO: move this logic outside %>
|
87
|
+
<% route[:examples].each do |example| %>
|
88
|
+
<article class="example <%= verb.downcase %>">
|
89
|
+
<details>
|
90
|
+
<summary class="example <%= verb.downcase %>"><%= example['description'] %></summary>
|
91
|
+
<div class="example_content <%= verb.downcase %>">
|
92
|
+
<div class="request">
|
93
|
+
<h4>Request</h4>
|
94
|
+
<div class="code <%= verb.downcase %>">
|
95
|
+
<div>
|
96
|
+
<h5>Query</h5>
|
97
|
+
<pre class='request-code query'><code class="json"><%= example['request']['query'] %></code></pre>
|
98
|
+
</div>
|
99
|
+
|
100
|
+
<% if example['request']['headers'] %>
|
101
|
+
<div>
|
102
|
+
<h5>Headers</h5>
|
103
|
+
<% example['request']['headers'].each do |key, value| %>
|
104
|
+
<pre class="request-code headers"><code class="json"><%= key %>: <%= value %></code></pre>
|
105
|
+
<% end %>
|
106
|
+
</div>
|
107
|
+
<% end %>
|
108
|
+
|
109
|
+
<% if example['request']['body'] %>
|
110
|
+
<div>
|
111
|
+
<h5>Body</h5>
|
112
|
+
<pre class='request-code body'><code class="json"><%= example['request']['body'] %></code></pre>
|
113
|
+
</div>
|
114
|
+
<% end %>
|
115
|
+
</div>
|
116
|
+
</div>
|
117
|
+
|
118
|
+
<div class="response">
|
119
|
+
<h4>Response (status <%= example['response']['status'] %>)</h4>
|
120
|
+
<div class="code <%= verb.downcase %>">
|
121
|
+
<% if example['response']['headers'] %>
|
122
|
+
<div>
|
123
|
+
<h5>Headers</h5>
|
124
|
+
<% example['response']['headers'].each do |key, value| %>
|
125
|
+
<pre class="request-code headers"><code class="json"><%= key %>: <%= value %></code></pre>
|
126
|
+
<% end %>
|
127
|
+
</div>
|
128
|
+
<% end %>
|
129
|
+
|
130
|
+
<div>
|
131
|
+
<h5>Body</h5>
|
132
|
+
<% if example['response']['body'] %>
|
133
|
+
<pre class='request-code body'><code class="json"><%= example['response']['body'] %></code></pre>
|
134
|
+
<% else %>
|
135
|
+
<pre class='request-code body'><code class="json">No body</code></pre>
|
136
|
+
<% end %>
|
137
|
+
</div>
|
138
|
+
</div>
|
139
|
+
</div>
|
140
|
+
</div>
|
141
|
+
</details>
|
142
|
+
</article>
|
143
|
+
<% end %>
|
144
|
+
</div>
|
145
|
+
<% end %>
|
146
|
+
</div>
|
147
|
+
</details>
|
148
|
+
</article>
|
149
|
+
<% end %>
|
150
|
+
</details>
|
151
|
+
</article>
|
152
|
+
<% end %>
|
153
|
+
</section>
|
154
|
+
</section>
|
@@ -12,28 +12,43 @@ module DocMyRoutes
|
|
12
12
|
|
13
13
|
# Inner class to maintain configuration settings
|
14
14
|
class Config
|
15
|
+
class UnsupportedFormat < RuntimeError; end
|
16
|
+
|
15
17
|
attr_accessor :title, # Project title
|
16
18
|
:description, # Project description
|
17
19
|
:destination_dir, # Where to store the documentation
|
18
20
|
:css_file_path, # Path to look for a CSS file
|
19
21
|
:examples_path_regexp # Path regexp to example files
|
20
|
-
attr_reader :index_template_file # Template used for the index.html
|
22
|
+
attr_reader :index_template_file, # Template used for the index.html
|
23
|
+
:partial_template_file,
|
24
|
+
:format
|
21
25
|
|
22
26
|
def initialize
|
23
27
|
@title = @description = @examples_path_regexp = nil
|
24
28
|
|
25
29
|
@destination_dir = File.join(Dir.pwd, 'doc', 'api')
|
30
|
+
@format = :html
|
31
|
+
@partial = false
|
26
32
|
|
27
33
|
default_static_path = File.join(File.dirname(__FILE__), '..', '..',
|
28
34
|
'..', 'etc')
|
29
35
|
@css_file_path = File.join(default_static_path, 'css', 'base.css')
|
30
36
|
@index_template_file = File.join(default_static_path, 'index.html.erb')
|
37
|
+
@partial_template_file = File.join(default_static_path, 'partial.html.erb')
|
31
38
|
end
|
32
39
|
|
33
40
|
def examples
|
34
41
|
@examples_path_regexp.nil? ? [] : Dir.glob(@examples_path_regexp)
|
35
42
|
end
|
36
43
|
|
44
|
+
def format=(format = :html)
|
45
|
+
@format = format.to_sym
|
46
|
+
fail UnsupportedFormat,
|
47
|
+
"The output format must be :html or :partial_format. It is #{@format}" \
|
48
|
+
unless %i(html partial_html).include?(@format)
|
49
|
+
@partial = true
|
50
|
+
end
|
51
|
+
|
37
52
|
# Calculate the relative path of the CSS used
|
38
53
|
def destination_css
|
39
54
|
# TODO: make it more robust
|
@@ -41,7 +56,8 @@ module DocMyRoutes
|
|
41
56
|
end
|
42
57
|
|
43
58
|
def index_file
|
44
|
-
|
59
|
+
filename = @partial ? 'index_partial.html' : 'index.html'
|
60
|
+
File.join(@destination_dir, filename)
|
45
61
|
end
|
46
62
|
end
|
47
63
|
end
|
@@ -19,7 +19,7 @@ module DocMyRoutes
|
|
19
19
|
|
20
20
|
def generate
|
21
21
|
generate_content
|
22
|
-
|
22
|
+
generate_output
|
23
23
|
copy_css_files
|
24
24
|
end
|
25
25
|
|
@@ -54,13 +54,41 @@ module DocMyRoutes
|
|
54
54
|
}
|
55
55
|
end
|
56
56
|
|
57
|
-
def
|
58
|
-
|
57
|
+
def generate_output
|
58
|
+
case @config.format
|
59
|
+
when :html
|
60
|
+
generate_html
|
61
|
+
when :partial_html
|
62
|
+
generate_partial_html
|
63
|
+
end
|
64
|
+
end
|
65
|
+
|
66
|
+
def partial_html
|
67
|
+
partial_binding = OpenStruct.new(data: content)
|
59
68
|
.instance_eval { binding }
|
60
69
|
index_file = @config.index_file
|
70
|
+
|
71
|
+
template_file = File.read(@config.partial_template_file)
|
72
|
+
ERB.new(template_file, 0, '<>').result(partial_binding)
|
73
|
+
end
|
74
|
+
|
75
|
+
def generate_partial_html
|
76
|
+
index_file = @config.index_file
|
77
|
+
|
78
|
+
File.open(index_file, 'w') do |f|
|
79
|
+
f.write partial_html
|
80
|
+
end
|
81
|
+
DocMyRoutes.logger.info "Generated Partial HTML file to #{index_file}"
|
82
|
+
end
|
83
|
+
|
84
|
+
def generate_html
|
85
|
+
index_file = @config.index_file
|
86
|
+
html_binding = OpenStruct.new(body: partial_html, title: content[:main][:info][:title])
|
87
|
+
.instance_eval { binding }
|
88
|
+
|
61
89
|
File.open(index_file, 'w') do |f|
|
62
90
|
template_file = File.read(@config.index_template_file)
|
63
|
-
content = ERB.new(template_file, 0, '<>').result(
|
91
|
+
content = ERB.new(template_file, 0, '<>').result(html_binding)
|
64
92
|
f.write content
|
65
93
|
end
|
66
94
|
DocMyRoutes.logger.info "Generated HTML file to #{index_file}"
|
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: doc_my_routes
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.
|
4
|
+
version: 0.10.0
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Workday, Ltd.
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date:
|
11
|
+
date: 2016-01-25 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: bundler
|
@@ -94,6 +94,20 @@ dependencies:
|
|
94
94
|
- - ">="
|
95
95
|
- !ruby/object:Gem::Version
|
96
96
|
version: '0'
|
97
|
+
- !ruby/object:Gem::Dependency
|
98
|
+
name: nokogiri
|
99
|
+
requirement: !ruby/object:Gem::Requirement
|
100
|
+
requirements:
|
101
|
+
- - ">="
|
102
|
+
- !ruby/object:Gem::Version
|
103
|
+
version: '0'
|
104
|
+
type: :development
|
105
|
+
prerelease: false
|
106
|
+
version_requirements: !ruby/object:Gem::Requirement
|
107
|
+
requirements:
|
108
|
+
- - ">="
|
109
|
+
- !ruby/object:Gem::Version
|
110
|
+
version: '0'
|
97
111
|
description: DocMyRoutes provides a way to annotate Sinatra routes and generate documentation
|
98
112
|
email:
|
99
113
|
- prd.eng.os@workday.com
|
@@ -103,6 +117,7 @@ extra_rdoc_files: []
|
|
103
117
|
files:
|
104
118
|
- etc/css/base.css
|
105
119
|
- etc/index.html.erb
|
120
|
+
- etc/partial.html.erb
|
106
121
|
- lib/doc_my_routes.rb
|
107
122
|
- lib/doc_my_routes/doc/config.rb
|
108
123
|
- lib/doc_my_routes/doc/documentation.rb
|