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