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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 17f3f57b0db1830d87f264ed478993bddae46dbf
4
- data.tar.gz: 76ae901bacabe4b66368d80b8923e05ff1082d73
3
+ metadata.gz: df089a5bc4bd8767575912bd945d21d61e1f130a
4
+ data.tar.gz: 5bcfac44baee8a2e7181c5fca1c64b93218d4ae3
5
5
  SHA512:
6
- metadata.gz: d1f10d35fc3cf4c1715e5178d2fd4dca41379a6b4c97fc501373902d8c9488c4acab9a2f7f0cf6a7c7b381fccff49a19bdb435f3d36323f810a9fa754494d436
7
- data.tar.gz: b9d11ecabb6012c7ac888cdf837fabe96c3c80b0e95c7c93b45c1d5a6959c7ed36cfb9fb7db1690be9ef8e9f0ef1bf7784a6d7964961be23a4340b36475f29a3
6
+ metadata.gz: 1d92bc03a756b62a923691850b12553360a721460df0549cf91a64f20312f846625468c25d158b296f066932cd4bcb51748b9a9412891f133b8e2565a4a8231c
7
+ data.tar.gz: 7205b1029816eb138f513e7efe6d710242db5c1a78e4979c1d0ae658c17e0eb0ae2b4bce7c5ef94a218b8f47f495da168b5ffc3142949a05a00abf563758366e
data/bin/raindoc CHANGED
@@ -7,6 +7,7 @@ end
7
7
  $:.unshift(File.join(File.dirname(File.expand_path(path)), '..', 'lib'))
8
8
 
9
9
  require 'doc'
10
+ require 'output'
10
11
  require 'rain'
11
12
 
12
13
  Rain::CLI.start(ARGV)
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
- @@docs << @doc
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
@@ -0,0 +1,6 @@
1
+ header_img_url: 'img/logo.png'
2
+ api_title: 'Rain API Documentation'
3
+ api_url: 'http://martin-brennan.github.io/rain'
4
+ api_version: '0.0.1'
5
+ source_url: 'https://github.com/martin-brennan/rain'
6
+ company_name: 'Rain'
@@ -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"] %>]&nbsp;
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">&nbsp;</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>&copy; <%= rainopts["company_name"] %> <%= Time.now.year %>. All rights reserved.</p>
55
+ </div>
56
+ </div>
57
+ <div class="three columns">&nbsp;</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.6
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-20 00:00:00.000000000 Z
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 ebr-based template system."
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/