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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: bbc3ad0bfc94aa4b5af5ecd1560fb6b2ba7e6e8a
4
- data.tar.gz: 2bd15f0a53ac2ae5f0c0377dd409ec286bebf29a
3
+ metadata.gz: c573d2ed3d69b19c86e42facf512dceae2c25c15
4
+ data.tar.gz: 8e2b17bd3e31ed83c44b589661f73fb863c3432b
5
5
  SHA512:
6
- metadata.gz: 5c9de394718c92d0c895274b492b837a6c337b66ddd372cd93b66bbbd494d4adae634c7ef1c5aaca2221fae2c1f71855044541f3ea48014135d9da69e987a0ba
7
- data.tar.gz: 5ba49d62f21405d10a9be69a7bf071bed33f7d5e32bf498a6e3208d960f4eff0c05634a6e9aa4f2d54d7966ca8c00e084e236c32fd7931d86f8444e637b6d9ec
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><%= data[:main][:info][:title] %></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
- <section class="documentation">
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
- File.join(@destination_dir, 'index.html')
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
- generate_html
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 generate_html
58
- doc_binding = OpenStruct.new(data: content)
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(doc_binding)
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}"
@@ -1,4 +1,4 @@
1
1
  # DocMyRoutes version
2
2
  module DocMyRoutes
3
- VERSION = '0.9.0'
3
+ VERSION = '0.10.0'
4
4
  end
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.9.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: 2015-11-23 00:00:00.000000000 Z
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