rain-doc 0.0.6 → 0.0.7
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/bin/raindoc +1 -0
- data/lib/output.rb +180 -0
- data/lib/rain.rb +13 -115
- data/rainopts.yml +6 -0
- data/templates/css/rain.css +11 -0
- data/templates/img/logo.png +0 -0
- data/templates/layout.erb +37 -0
- metadata +6 -3
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: df089a5bc4bd8767575912bd945d21d61e1f130a
|
4
|
+
data.tar.gz: 5bcfac44baee8a2e7181c5fca1c64b93218d4ae3
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 1d92bc03a756b62a923691850b12553360a721460df0549cf91a64f20312f846625468c25d158b296f066932cd4bcb51748b9a9412891f133b8e2565a4a8231c
|
7
|
+
data.tar.gz: 7205b1029816eb138f513e7efe6d710242db5c1a78e4979c1d0ae658c17e0eb0ae2b4bce7c5ef94a218b8f47f495da168b5ffc3142949a05a00abf563758366e
|
data/bin/raindoc
CHANGED
data/lib/output.rb
ADDED
@@ -0,0 +1,180 @@
|
|
1
|
+
module Rain
|
2
|
+
class Output
|
3
|
+
|
4
|
+
# Builds the HTML for each doc in thedocs array after
|
5
|
+
# parsing all of the files specified.
|
6
|
+
def build_html(docs, rainopts)
|
7
|
+
|
8
|
+
# delete the old output files and create the dir
|
9
|
+
FileUtils.rm_rf('./rain_out')
|
10
|
+
Dir.mkdir('./rain_out')
|
11
|
+
Dir.mkdir('./rain_out/css')
|
12
|
+
Dir.mkdir('./rain_out/js')
|
13
|
+
Dir.mkdir('./rain_out/img')
|
14
|
+
|
15
|
+
# check if there are local templates before copying from gem dir
|
16
|
+
if File.exist?('./templates/') && File.exist?('./templates/css/')
|
17
|
+
|
18
|
+
# copy the template css + js to the output dir
|
19
|
+
FileUtils.cp_r './templates/css/.', './rain_out/css'
|
20
|
+
FileUtils.cp_r './templates/js/.', './rain_out/js'
|
21
|
+
FileUtils.cp_r './templates/img/.', './rain_out/img'
|
22
|
+
|
23
|
+
# load the templates
|
24
|
+
layout_template = File.read('./templates/layout.erb')
|
25
|
+
doc_template = File.read('./templates/doc.erb')
|
26
|
+
nav_template = File.read('./templates/nav.erb')
|
27
|
+
|
28
|
+
else
|
29
|
+
|
30
|
+
# copy the templates from the gem directory
|
31
|
+
spec = Gem::Specification.find_by_name("rain-doc")
|
32
|
+
FileUtils.cp_r spec.gem_dir + '/templates/css/.', './rain_out/css'
|
33
|
+
FileUtils.cp_r spec.gem_dir + '/templates/js/.', './rain_out/js'
|
34
|
+
FileUtils.cp_r spec.gem_dir + '/templates/img/.', './rain_out/img'
|
35
|
+
|
36
|
+
# load the templates
|
37
|
+
layout_template = File.read(spec.gem_dir + '/templates/layout.erb')
|
38
|
+
doc_template = File.read(spec.gem_dir + '/templates/doc.erb')
|
39
|
+
nav_template = File.read(spec.gem_dir + '/templates/nav.erb')
|
40
|
+
end
|
41
|
+
|
42
|
+
# loop through all of the docs and generate navigation from the docs and their parts
|
43
|
+
nav_parts = []
|
44
|
+
docs.each do |doc|
|
45
|
+
nav_parts << render_nav(doc, nav_template)
|
46
|
+
end
|
47
|
+
|
48
|
+
# load the custom css file paths from templates/css.
|
49
|
+
custom_css = find_custom_css
|
50
|
+
|
51
|
+
# load the custom js file paths from templates/js.
|
52
|
+
custom_js = find_custom_js
|
53
|
+
|
54
|
+
# load the doc properties and parts into the doc template
|
55
|
+
docs.each do |doc|
|
56
|
+
|
57
|
+
# create an openstruct from the current doc and render into the template
|
58
|
+
doc_os = OpenStruct.new(doc.to_hash)
|
59
|
+
doc_rendered = ERB.new(doc_template).result(doc_os.instance_eval {binding})
|
60
|
+
|
61
|
+
# create a struct with the rendered doc output then render into the layout with nav
|
62
|
+
layout_os = OpenStruct.new({
|
63
|
+
doc_output: doc_rendered,
|
64
|
+
title: doc_os.title,
|
65
|
+
nav_parts: nav_parts,
|
66
|
+
custom_css: custom_css,
|
67
|
+
custom_js: custom_js,
|
68
|
+
rainopts: rainopts
|
69
|
+
})
|
70
|
+
|
71
|
+
html = ERB.new(layout_template).result(layout_os.instance_eval {binding})
|
72
|
+
|
73
|
+
# write the html to a file
|
74
|
+
output_html(doc, html)
|
75
|
+
end
|
76
|
+
end
|
77
|
+
|
78
|
+
# renders the nav block for the doc specified,
|
79
|
+
# including the navigation tree for subitems.
|
80
|
+
#
|
81
|
+
# {param doc Rain::Doc}
|
82
|
+
# The doc to use for the navigation block.
|
83
|
+
# {/param}
|
84
|
+
# {param nav_template String}
|
85
|
+
# The navigation template from templates/nav.erb
|
86
|
+
# {/param}
|
87
|
+
def render_nav(doc, nav_template)
|
88
|
+
|
89
|
+
# get the html file name (same used for output) from the doc openstruct
|
90
|
+
doc_os = OpenStruct.new(doc.to_hash)
|
91
|
+
html_file_name = File.basename(doc_os.file_name, doc_os.file_ext) + '.html'
|
92
|
+
|
93
|
+
# set up the nav hash for the doc
|
94
|
+
nav = {
|
95
|
+
navdoc: {
|
96
|
+
title: doc_os.title,
|
97
|
+
url: "#{html_file_name}",
|
98
|
+
parts: []
|
99
|
+
}
|
100
|
+
}
|
101
|
+
|
102
|
+
# markdown docs do not have parts as the whole page counts as a "doc"
|
103
|
+
if doc_os.type != "MARKDOWN"
|
104
|
+
|
105
|
+
# loop through all of the parts and depending on whether
|
106
|
+
# it is for a signature or a route, construct the #anchor
|
107
|
+
# url differnetly
|
108
|
+
doc_os.parts.each do |part|
|
109
|
+
if !part[:signature].nil?
|
110
|
+
nav[:navdoc][:parts] << {
|
111
|
+
title: part[:signature],
|
112
|
+
url: "#{html_file_name}##{part[:signature].gsub(' ', '-').gsub(',', '').gsub('(', '-').gsub(')', '-')[0..12]}"
|
113
|
+
}
|
114
|
+
else
|
115
|
+
nav[:navdoc][:parts] << {
|
116
|
+
title: part[:route],
|
117
|
+
url: "#{html_file_name}##{part[:http_method].downcase}#{part[:route].gsub('/', '-').gsub(':', '')}"
|
118
|
+
}
|
119
|
+
end
|
120
|
+
end
|
121
|
+
end
|
122
|
+
|
123
|
+
# render the nav and append it to the array of nav parts
|
124
|
+
nav_os = OpenStruct.new(nav)
|
125
|
+
nav_rendered = ERB.new(nav_template).result(nav_os.instance_eval {binding})
|
126
|
+
end
|
127
|
+
|
128
|
+
# loads the custom css files (e.g. not skeleton, normalise and rain.css)
|
129
|
+
# from the templates/css path.
|
130
|
+
def find_custom_css
|
131
|
+
|
132
|
+
# loop through all of the css files in the output dir
|
133
|
+
# to see if any are custom files.
|
134
|
+
default_files = ['skeleton.css', 'normalize.css', 'rain.css']
|
135
|
+
custom_css = []
|
136
|
+
Dir.foreach('./rain_out/css') do |file_name|
|
137
|
+
if !default_files.include?(file_name) && file_name != '.' && file_name != '..'
|
138
|
+
custom_css << "css/#{file_name}"
|
139
|
+
end
|
140
|
+
end
|
141
|
+
|
142
|
+
custom_css
|
143
|
+
end
|
144
|
+
|
145
|
+
# loads the custom js files (e.g. not skeleton, normalise and rain.js)
|
146
|
+
# from the templates/js path.
|
147
|
+
def find_custom_js
|
148
|
+
|
149
|
+
# loop through all of the js files in the output dir
|
150
|
+
# to see if any are custom files.
|
151
|
+
custom_js = []
|
152
|
+
Dir.foreach('./rain_out/js') do |file_name|
|
153
|
+
if file_name != '.' && file_name != '..'
|
154
|
+
custom_js << "js/#{file_name}"
|
155
|
+
end
|
156
|
+
end
|
157
|
+
|
158
|
+
custom_js
|
159
|
+
end
|
160
|
+
|
161
|
+
# Creates the html file for the specified doc
|
162
|
+
# with the HTML rendered from the ERB template
|
163
|
+
#
|
164
|
+
# {param doc hash}
|
165
|
+
# A hash representation of the Rain::Doc class, containing a single document and its parts.
|
166
|
+
# {/param}
|
167
|
+
# {param html string}
|
168
|
+
# The HTML rendered from the ERB layout and doc template.
|
169
|
+
# {/param}
|
170
|
+
def output_html(doc, html)
|
171
|
+
|
172
|
+
# replace file_name extenstions with .html
|
173
|
+
file_name = File.basename(doc.file_name, doc.file_ext) + '.html'
|
174
|
+
|
175
|
+
# write the output to the file
|
176
|
+
File.open("./rain_out/#{file_name}", 'w') { |file| file.write(html) }
|
177
|
+
end
|
178
|
+
|
179
|
+
end
|
180
|
+
end
|
data/lib/rain.rb
CHANGED
@@ -2,9 +2,9 @@ require 'thor'
|
|
2
2
|
require 'erb'
|
3
3
|
require 'ostruct'
|
4
4
|
require 'fileutils'
|
5
|
+
require 'yaml'
|
5
6
|
|
6
7
|
class Rain::CLI < Thor
|
7
|
-
@@docs = []
|
8
8
|
|
9
9
|
# loops through all of the specified source
|
10
10
|
# files, parses them line by line and produces
|
@@ -16,16 +16,26 @@ class Rain::CLI < Thor
|
|
16
16
|
print "Rain is parsing files in the directories #{sources} \n"
|
17
17
|
|
18
18
|
# loop through all of the file sources and generate docs
|
19
|
+
all_docs = []
|
19
20
|
sources.each do |source|
|
20
21
|
print "Parsing #{source} \n"
|
21
22
|
@doc = Rain::Doc.new(source, File.read(Dir.pwd + "/#{source}"), options[:log_parse].nil? ? false : true, options[:parse_signatures].nil? ? false : true)
|
22
23
|
@doc.parse
|
23
24
|
|
24
|
-
|
25
|
+
all_docs << @doc
|
26
|
+
end
|
27
|
+
|
28
|
+
# load the rainopts.yml file from local location (if it exists). otherwise use the default
|
29
|
+
# one from the gem dir.
|
30
|
+
if File.exist?('./rainopts.yml')
|
31
|
+
rainopts = YAML.load_file('./rainopts.yml')
|
32
|
+
else
|
33
|
+
spec = Gem::Specification.find_by_name("rain-doc")
|
34
|
+
rainopts = File.read(spec.gem_dir + '/rainopts.yml')
|
25
35
|
end
|
26
36
|
|
27
37
|
print "\nBuilding html output... \n"
|
28
|
-
build_html
|
38
|
+
Rain::Output.new.build_html(all_docs, rainopts)
|
29
39
|
print "\nDone! See rain_out/ directory for output.\n"
|
30
40
|
end
|
31
41
|
|
@@ -47,116 +57,4 @@ class Rain::CLI < Thor
|
|
47
57
|
print " --lp logs all line parsing output to console\n"
|
48
58
|
print " --s generates docs for methods and class signatures\n"
|
49
59
|
end
|
50
|
-
|
51
|
-
no_commands do
|
52
|
-
|
53
|
-
# Builds the HTML for each doc in the @@docs array.
|
54
|
-
def build_html
|
55
|
-
|
56
|
-
# delete the old output files and create the dir
|
57
|
-
FileUtils.rm_rf('./rain_out')
|
58
|
-
Dir.mkdir('./rain_out')
|
59
|
-
Dir.mkdir('./rain_out/css')
|
60
|
-
|
61
|
-
# check if there are local templates before copying from gem dir
|
62
|
-
if File.exist?('./templates/') && File.exist?('./templates/css/')
|
63
|
-
|
64
|
-
# copy the template css to the output dir
|
65
|
-
FileUtils.cp_r './templates/css/.', './rain_out/css'
|
66
|
-
|
67
|
-
# load the templates
|
68
|
-
layout_template = File.read('./templates/layout.erb')
|
69
|
-
doc_template = File.read('./templates/doc.erb')
|
70
|
-
nav_template = File.read('./templates/nav.erb')
|
71
|
-
|
72
|
-
else
|
73
|
-
|
74
|
-
# copy the templates from the gem directory
|
75
|
-
spec = Gem::Specification.find_by_name("rain-doc")
|
76
|
-
FileUtils.cp_r spec.gem_dir + '/templates/css/.', './rain_out/css'
|
77
|
-
|
78
|
-
# load the templates
|
79
|
-
layout_template = File.read(spec.gem_dir + '/templates/layout.erb')
|
80
|
-
doc_template = File.read(spec.gem_dir + '/templates/doc.erb')
|
81
|
-
nav_template = File.read(spec.gem_dir + '/templates/nav.erb')
|
82
|
-
end
|
83
|
-
|
84
|
-
# loop through all of the docs and generate navigation from the docs and their parts
|
85
|
-
nav_parts = []
|
86
|
-
@@docs.each do |doc|
|
87
|
-
|
88
|
-
# get the html file name (same used for output) from the doc openstruct
|
89
|
-
doc_os = OpenStruct.new(doc.to_hash)
|
90
|
-
html_file_name = File.basename(doc_os.file_name, doc_os.file_ext) + '.html'
|
91
|
-
|
92
|
-
# set up the nav hash for the doc
|
93
|
-
nav = {
|
94
|
-
navdoc: {
|
95
|
-
title: doc_os.title,
|
96
|
-
url: "#{html_file_name}",
|
97
|
-
parts: []
|
98
|
-
}
|
99
|
-
}
|
100
|
-
|
101
|
-
# markdown docs do not have parts as the whole page counts as a "doc"
|
102
|
-
if doc_os.type != "MARKDOWN"
|
103
|
-
|
104
|
-
# loop through all of the parts and depending on whether
|
105
|
-
# it is for a signature or a route, construct the #anchor
|
106
|
-
# url differnetly
|
107
|
-
doc_os.parts.each do |part|
|
108
|
-
if !part[:signature].nil?
|
109
|
-
nav[:navdoc][:parts] << {
|
110
|
-
title: part[:signature],
|
111
|
-
url: "#{html_file_name}##{part[:signature].gsub(' ', '-').gsub(',', '').gsub('(', '-').gsub(')', '-')[0..12]}"
|
112
|
-
}
|
113
|
-
else
|
114
|
-
nav[:navdoc][:parts] << {
|
115
|
-
title: part[:route],
|
116
|
-
url: "#{html_file_name}##{part[:http_method].downcase}#{part[:route].gsub('/', '-').gsub(':', '')}"
|
117
|
-
}
|
118
|
-
end
|
119
|
-
end
|
120
|
-
end
|
121
|
-
|
122
|
-
# render the nav and append it to the array of nav parts
|
123
|
-
nav_os = OpenStruct.new(nav)
|
124
|
-
nav_rendered = ERB.new(nav_template).result(nav_os.instance_eval {binding})
|
125
|
-
nav_parts << nav_rendered
|
126
|
-
end
|
127
|
-
|
128
|
-
# load the doc properties and parts into the doc template
|
129
|
-
@@docs.each do |doc|
|
130
|
-
|
131
|
-
# create an openstruct from the current doc and render into the template
|
132
|
-
doc_os = OpenStruct.new(doc.to_hash)
|
133
|
-
doc_rendered = ERB.new(doc_template).result(doc_os.instance_eval {binding})
|
134
|
-
|
135
|
-
# create a struct with the rendered doc output then render into the layout with nav
|
136
|
-
layout_os = OpenStruct.new({ doc_output: doc_rendered, title: doc_os.title, nav_parts: nav_parts })
|
137
|
-
html = ERB.new(layout_template).result(layout_os.instance_eval {binding})
|
138
|
-
|
139
|
-
# write the html to a file
|
140
|
-
output_html(doc, html)
|
141
|
-
end
|
142
|
-
end
|
143
|
-
|
144
|
-
# Creates the html file for the specified doc
|
145
|
-
# with the HTML rendered from the ERB template
|
146
|
-
#
|
147
|
-
# {param doc hash}
|
148
|
-
# A hash representation of the Rain::Doc class, containing a single document and its parts.
|
149
|
-
# {/param}
|
150
|
-
# {param html string}
|
151
|
-
# The HTML rendered from the ERB layout and doc template.
|
152
|
-
# {/param}
|
153
|
-
def output_html(doc, html)
|
154
|
-
|
155
|
-
# replace file_name extenstions with .html
|
156
|
-
file_name = File.basename(doc.file_name, doc.file_ext) + '.html'
|
157
|
-
|
158
|
-
# write the output to the file
|
159
|
-
File.open("./rain_out/#{file_name}", 'w') { |file| file.write(html) }
|
160
|
-
end
|
161
|
-
end
|
162
60
|
end
|
data/rainopts.yml
ADDED
data/templates/css/rain.css
CHANGED
@@ -33,4 +33,15 @@ p {
|
|
33
33
|
}
|
34
34
|
.method-delete {
|
35
35
|
background-color: #e54400;
|
36
|
+
}
|
37
|
+
|
38
|
+
/* Footer and rain version information styles */
|
39
|
+
.rain-version-info {
|
40
|
+
text-align: center;
|
41
|
+
}
|
42
|
+
|
43
|
+
.rain-version-info p {
|
44
|
+
font-size: 80%;
|
45
|
+
color: #ccc;
|
46
|
+
margin: 4px 0;
|
36
47
|
}
|
Binary file
|
data/templates/layout.erb
CHANGED
@@ -4,9 +4,34 @@
|
|
4
4
|
<link rel="stylesheet" type="text/css" href="css/normalize.css" />
|
5
5
|
<link rel="stylesheet" type="text/css" href="css/skeleton.css" />
|
6
6
|
<link rel="stylesheet" type="text/css" href="css/rain.css" />
|
7
|
+
<% custom_css.each do |css| %>
|
8
|
+
<link rel="stylesheet" type="text/css" href="<%= css %>" />
|
9
|
+
<% end %>
|
10
|
+
<% custom_js.each do |js| %>
|
11
|
+
<script type="text/javascript" src="<%= js %>"></script>
|
12
|
+
<% end %>
|
7
13
|
</head>
|
8
14
|
<body>
|
9
15
|
<div class="container">
|
16
|
+
<div class="row" id="header" style="margin-top: 20px;">
|
17
|
+
<div class="two columns">
|
18
|
+
<% if !rainopts["header_img_url"].nil? %>
|
19
|
+
<img style="margin: 0 auto; width: 80%;" src="<%= rainopts["header_img_url"] %>" />
|
20
|
+
<% end %>
|
21
|
+
</div>
|
22
|
+
<div class="ten columns">
|
23
|
+
<h4 style="margin-bottom: 0;"><%= rainopts["api_title"] %></h4>
|
24
|
+
<p style="margin: 0;">
|
25
|
+
[v<%= rainopts["api_version"].nil? ? '0.0.0' : rainopts["api_version"] %>]
|
26
|
+
<a href="<%= rainopts["api_url"] %>"><%= rainopts["api_url"] %></a>
|
27
|
+
</p>
|
28
|
+
<p style="margin: 0;">
|
29
|
+
<% if !rainopts["source_url"].nil? %>
|
30
|
+
See source at <a href="<%= rainopts["source_url"] %>"><%= rainopts["source_url"] %></a>
|
31
|
+
<% end %>
|
32
|
+
</p>
|
33
|
+
</div>
|
34
|
+
</div>
|
10
35
|
<div class="row">
|
11
36
|
<div class="three columns" style="padding: 20px 0">
|
12
37
|
<h5>Navigation</h5>
|
@@ -19,6 +44,18 @@
|
|
19
44
|
<%= doc_output %>
|
20
45
|
</div>
|
21
46
|
</div>
|
47
|
+
<div class="row" id="footer">
|
48
|
+
<div class="three columns"> </div>
|
49
|
+
<div class="six columns">
|
50
|
+
<div class="rain-version-info">
|
51
|
+
<p>Rain v<%= Gem::Specification.find_by_name("rain-doc").version.to_s %></p>
|
52
|
+
<p>See source at <a href="https://github.com/martin-brennan/rain">https://github.com/martin-brennan/rain</a>.</p>
|
53
|
+
<p>Gem at <a href="https://rubygems.org/gems/rain-doc">https://rubygems.org/gems/rain-doc</a></p>
|
54
|
+
<p>© <%= rainopts["company_name"] %> <%= Time.now.year %>. All rights reserved.</p>
|
55
|
+
</div>
|
56
|
+
</div>
|
57
|
+
<div class="three columns"> </div>
|
58
|
+
</div>
|
22
59
|
</div>
|
23
60
|
</body>
|
24
61
|
</html>
|
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: rain-doc
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.0.
|
4
|
+
version: 0.0.7
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Martin Brennan
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date: 2014-12-
|
11
|
+
date: 2014-12-22 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: rspec
|
@@ -59,7 +59,7 @@ description: "Rain is a gem to generate beautiful and customizable API documenta
|
|
59
59
|
architecture documentation. Rain also allows a large amount of
|
60
60
|
customization when it comes to templating and appearance of the API documentation.
|
61
61
|
\ Branding and unity of documentation appearance is important
|
62
|
-
and Rain offers a simple
|
62
|
+
and Rain offers a simple ERB-based template system."
|
63
63
|
email: mjrbrennan@gmail.com
|
64
64
|
executables:
|
65
65
|
- raindoc
|
@@ -69,12 +69,15 @@ files:
|
|
69
69
|
- bin/raindoc
|
70
70
|
- lib/doc.rb
|
71
71
|
- lib/doc_part.rb
|
72
|
+
- lib/output.rb
|
72
73
|
- lib/parser.rb
|
73
74
|
- lib/rain.rb
|
75
|
+
- rainopts.yml
|
74
76
|
- templates/css/normalize.css
|
75
77
|
- templates/css/rain.css
|
76
78
|
- templates/css/skeleton.css
|
77
79
|
- templates/doc.erb
|
80
|
+
- templates/img/logo.png
|
78
81
|
- templates/layout.erb
|
79
82
|
- templates/nav.erb
|
80
83
|
homepage: http://martin-brennan.github.io/rain/
|