doc_my_routes 0.9.0 → 0.10.0

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 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