rain-doc 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/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/
|