rdoc-babel 1.2.0 → 1.4.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
  SHA256:
3
- metadata.gz: 55f4e3e723fcdd5967ec422747a0de38dba85db8c8a7e3592232e67346b3aa92
4
- data.tar.gz: '0855f9b0383d9b91ada6369e90436d8d9532d4116f8d2fb29369c3bdb1e13864'
3
+ metadata.gz: 11de5544dfb3dea6db68f549a905deb714ba445bfc02ebff7e2e54f7c4e2cae3
4
+ data.tar.gz: 7517f06eafd50bf7107645a47e206ab85ad2d04f743baa76d026c4664ef41ec5
5
5
  SHA512:
6
- metadata.gz: 77548381b3e7ed0f445016295b94eb7498f8d84686fa5df90319ec72138d4ab12d07f2e872bae59b54e4acc79506c85e2f39727dc5e20809f9852ebdffe70ba2
7
- data.tar.gz: d3a6fd0e292026ece7ceefdd68f6654e7ebef7c6c3aca5d41283927e830c13679ac9fa198980e26c2b52b86452bf00df58d563f61e50e8f4d057cb5cc9537ad0
6
+ metadata.gz: 9afb98e8a4e926772fc79b43b741222f1d7ceaf960f1f7157b5c4ca78137031d3eaf6f586851e7cfdac2df921850504f5e8414c7a1aca9fae67f7d825b2fa027
7
+ data.tar.gz: dbbe9dee9014d525008d60d73ead16f53258125d28712c8ccf2fecf5266e7960707d6c34b71f3c95c684c30c604e91f95d2b4258fe88c8ca9d93056fc89fa18b
data/HISTORY.rdoc CHANGED
@@ -1,3 +1,18 @@
1
+ === 1.4.0
2
+
3
+ * add a TOC button on the top right
4
+ * fix initial sizing in the left pane
5
+ * fix too wide <pre> sections
6
+
7
+ === 1.3.0
8
+
9
+ * switch from frameset to iframe
10
+ * highlight the current file/class/method in the left frame
11
+
12
+ === 1.2.1
13
+
14
+ * filter: only search in link text (skip class/method type)
15
+
1
16
  === 1.2.0
2
17
 
3
18
  * add resizing of indexes in left frame
data/README.rdoc CHANGED
@@ -16,39 +16,40 @@ and to contribute alternate templates or style sheets.
16
16
  - Dual-frame output, with indexes on the left.
17
17
  - Search boxes for classes and methods.
18
18
  - Links to undocumented classes/methods are grayed.
19
- - Highlights target methods, attributes and constants.
19
+ - Highlights the current file/class/method in the left frame.
20
+ - Highlights the target method, attribute or constant in the main frame.
20
21
  - Adds links to ancestor methods/attributes.
21
22
  - Borrows some ideas (and one icon) from Darkfish.
22
- - Tested on Firefox 3.5 & 5, Chrome 9 & 12, Safari 4 & 5.
23
+ - Tested on Firefox 125.<br>
24
+ If using the <tt>file://</tt> protocol, the "same origin policy" for local files must be turned off:<br>
25
+ <tt>about:config</tt> > <tt>security.fileuri.strict_origin_policy = false</tt>
23
26
 
24
27
  == Synopsis
25
28
 
26
29
  To output documentation formatted by Babel, use the <tt>--format/-f</tt>
27
- RDoc switch. For instance, to generate the documentation for Ruby core:
30
+ RDoc switch. For instance, to generate the documentation for Ruby core and stdlib:
28
31
 
29
- $ gem install rdoc-babel
30
- $ cd ~/.rvm/src/ruby-1.8.7-p302
31
- $ rdoc -f babel -a -t "Ruby 1.8.7 Core" -o ~/docs/ruby_core_187 *.c
32
+ > gem install rdoc-babel
33
+ > cd /ruby/src
34
+ > rdoc -f babel -a -t "Ruby Core + Stdlib" -o /docs/ruby-core
32
35
 
33
36
  Using rake:
34
37
 
35
38
  require 'rdoc/task'
36
39
 
37
40
  RDoc::Task.new do |t|
38
- Dir.chdir '~/.rvm/src/ruby-1.9.2-p0'
41
+ Dir.chdir '/ruby/src'
39
42
  rdoc.options <<
40
43
  '--format' << 'babel' <<
41
44
  '--all'
42
- t.title = "Ruby 1.9.2 Core"
43
- t.rdoc_dir = '~/docs/ruby_core_192'
44
- t.rdoc_files.concat Dir['*.c']
45
+ t.title = "Ruby Core + Stdlib"
46
+ t.rdoc_dir = '/docs/ruby-core'
45
47
  end
46
48
 
47
49
  To make Babel the default format when generating RDoc documentation,
48
- define the RDOCOPT environment variable in the appropriate file
49
- (e.g., <tt>~/.bashrc</tt>):
50
+ define the RDOCOPT environment variable:
50
51
 
51
- export RDOCOPT="--format babel"
52
+ RDOCOPT="--format babel"
52
53
 
53
54
  == Specific options
54
55
 
@@ -70,8 +71,8 @@ Babel supports specific options in addition to the standard RDoc options:
70
71
 
71
72
  == Requirements
72
73
 
73
- - Ruby >= 2.3.0 (may work with >= 1.9.3, but untested)
74
- - RDoc >= 5.0 (may work with >= 4.0, but untested)
74
+ - Ruby >= 3.1.0 (may work with >= 2.5.0, but untested)
75
+ - RDoc >= 6.5.0 (may work with >= 5.0, but untested)
75
76
 
76
77
  == Installation
77
78
 
@@ -81,7 +82,7 @@ Babel supports specific options in addition to the standard RDoc options:
81
82
 
82
83
  (The MIT License)
83
84
 
84
- Copyright (c) 2010-2020 Thierry Lambert
85
+ Copyright (c) 2010-2024 Thierry Lambert
85
86
 
86
87
  Permission is hereby granted, free of charge, to any person obtaining
87
88
  a copy of this software and associated documentation files (the
@@ -33,7 +33,7 @@ class RDoc::Generator::Babel
33
33
 
34
34
  RDoc::RDoc.add_generator(self)
35
35
 
36
- VERSION = '1.2.0'
36
+ VERSION = '1.4.0'
37
37
  DESCRIPTION = 'Alternate HTML documentation'
38
38
 
39
39
  include ERB::Util
@@ -157,6 +157,25 @@ class RDoc::Generator::Babel
157
157
 
158
158
  def generate
159
159
 
160
+ # rdoc bug fix: public class/module methods appear as external_aliases (unresolved aliases)
161
+
162
+ @store.all_classes_and_modules.each do |cm|
163
+ next if cm.external_aliases.empty?
164
+ class_level_names = cm.method_list.select { |m| m.type == 'class' }.map(&:name)
165
+ cm.external_aliases.dup.each do |a|
166
+ cm.external_aliases.delete a if class_level_names.include?(a.name)
167
+ end
168
+ end
169
+
170
+ # other bug fix: method aliases with singleton mismatch
171
+
172
+ @store.all_classes_and_modules.each do |cm|
173
+ cm.class_method_list.each do |m|
174
+ m.is_alias_for.singleton = true if m.is_alias_for
175
+ m.aliases.each { |a| a.singleton = true }
176
+ end
177
+ end
178
+
160
179
  # set instance variables
161
180
 
162
181
  @output_dir = Pathname.new(@options.op_dir).expand_path(@source_dir)
@@ -178,11 +197,25 @@ class RDoc::Generator::Babel
178
197
  @simple_files
179
198
  end
180
199
 
181
- @main_file = @options.main_page && @all_files.find { |f| f.full_name == @options.main_page }
182
- if @main_file
183
- unless @files_to_display.find { |f| f.full_name == @options.main_page }
184
- @files_to_display.unshift @main_file
200
+ if @options.main_page
201
+ # look for a TopLevel matching the main page
202
+ @main_page = @all_files.find { |f| f.full_name == @options.main_page }
203
+ if @main_page
204
+ # TODO are there cases where main_page = 'README' for 'lib/README'?
205
+ unless @files_to_display.find { |f| f.full_name == @options.main_page }
206
+ @files_to_display.unshift @main_page
207
+ end
208
+ # look for a class/module with that name
209
+ else
210
+ match = @unique_classes_and_modules.find { |cm| cm.full_name == @options.main_page }
211
+ if match
212
+ @main_page = match
213
+ else
214
+ warn "no such page: --main #{@options.main_page}"
215
+ end
185
216
  end
217
+ else
218
+ @main_page = nil
186
219
  end
187
220
 
188
221
  # write the output
@@ -263,7 +296,7 @@ class RDoc::Generator::Babel
263
296
  # Returns the first +Context+ object to display in the main frame.
264
297
  # This is, in order:
265
298
  # - The file designated by the +main_page+ option,
266
- # if there is a +TopLevel+ with that name.
299
+ # if there is a +TopLevel+ or class/module with that name.
267
300
  # - The first simple file that contains a comment
268
301
  # (in the order given on the command line).
269
302
  # - The first class or module that contains a comment.
@@ -274,19 +307,30 @@ class RDoc::Generator::Babel
274
307
  # - The first file.
275
308
 
276
309
  def first_page
277
- # TODO are there cases where main_page = 'README' for 'lib/README'?
278
- if @options.main_page && (main_file = @all_files.find { |f| f.full_name == @options.main_page })
279
- main_file
310
+ if @main_page
311
+ debug_msg "main as --main: #{@main_page}"
312
+ @main_page
280
313
  elsif (file = @simple_files.first)
314
+ debug_msg "main as first simple file: #{file}"
281
315
  file
282
316
  elsif (cm = @unique_classes_and_modules.find { |k| !k.comment.empty? })
317
+ debug_msg "main as first module/class with comment: #{cm}"
283
318
  cm
284
- elsif (file = @files_with_comment.first)
285
- file
319
+ # this is not a simple file, so currently not displayed in files
320
+ # elsif (file = @files_with_comment.first)
321
+ # debug_msg "main as first file with comment: #{file}"
322
+ # file
286
323
  elsif !@unique_classes_and_modules.empty?
287
- @unique_classes_and_modules.find { |k| k.any_content } or
288
- @unique_classes_and_modules.first
324
+ cm = @unique_classes_and_modules.find { |k| k.any_content }
325
+ if cm
326
+ debug_msg "main as first module/class with any content: #{cm}"
327
+ else
328
+ debug_msg "main as first module/class (no content): #{cm}"
329
+ cm = @unique_classes_and_modules.first
330
+ end
331
+ cm
289
332
  else
333
+ debug_msg "main as first file: #{cm}"
290
334
  @all_files.first
291
335
  end
292
336
  end
@@ -450,9 +494,32 @@ protected
450
494
 
451
495
  return if @options.dry_run
452
496
 
497
+ # fix file cross-references
498
+ # rdoc:ref handling by RDoc requires that files and classes are stored in the
499
+ # root output directory, while we have files and classes in separate subdirectories
500
+ output.gsub!(/<a (.*?)\bhref="(.+?)"/) do |match|
501
+ atts = $1
502
+ href = $2
503
+ next match if href[0] == '#'
504
+ path, id = href.split('#')
505
+ # in classes/OptionParser.html:
506
+ # we find for instance <a href="optparse/tutorial_rdoc.html">Tutorial</a>
507
+ # which matches files/doc/optparse/tutorial_rdoc.html
508
+ matches = @all_files.select do |f|
509
+ f.path.end_with?(path) && f.path != path
510
+ end
511
+ next match if matches.empty?
512
+ # we replace optparse/tutorial_rdoc.html by ../files/doc/optparse/tutorial_rdoc.html
513
+ f = matches.first
514
+ actual = Pathname.new(f.path).expand_path(@output_dir).relative_path_from(outfile.dirname).to_s
515
+ next match if actual == path
516
+ actual << '#' << id if id
517
+ %(<a #{atts}href="#{actual}")
518
+ end
519
+
453
520
  outfile.dirname.mkpath
454
- outfile.open('w', 0644) do |ofh|
455
- ofh.print(output)
521
+ outfile.open('w', 0644) do |io|
522
+ io.print(output)
456
523
  end
457
524
 
458
525
  end
@@ -2,13 +2,18 @@
2
2
  <html lang="en">
3
3
  <head>
4
4
  <meta charset="<%= @options.charset %>">
5
- <title><%= @class.type.capitalize %> <%= @class.full_name %></title>
5
+ <title><%= @class.full_name %> &ndash; <%= h @options.title %></title>
6
6
  <link href="<%= @stylesheet_url %>" rel="stylesheet">
7
7
  <link href="https://fonts.googleapis.com/css?family=Noto+Sans" rel="stylesheet">
8
8
  <script src="<%= @rel_prefix %>/scripts/mainFrame.js" type="text/javascript"></script>
9
9
  </head>
10
10
  <body>
11
11
 
12
+ <div id="left-container">
13
+ <iframe id="left-frame" src="<%= @rel_prefix %>/indexes.html"></iframe>
14
+ <div id="resizer"></div>
15
+ </div>
16
+ <div id="main-container">
12
17
  <div id="header">
13
18
  <p class="header-title">
14
19
  <span class="prefix"><%= @class.type.capitalize %></span><span class="name"> <%= @class.full_name %></span>
@@ -69,8 +74,8 @@
69
74
 
70
75
  <%= @class.description %>
71
76
 
72
- <!-- class/module aliases -->
73
77
  <% unless @class.aliases.empty? %>
78
+ <!-- class/module aliases -->
74
79
  <div id="class-aliases" class="list">
75
80
  <h3><%= @class.type.capitalize %> Aliases</h3>
76
81
  <ul>
@@ -81,8 +86,8 @@
81
86
  </div>
82
87
  <% end %>
83
88
 
84
- <!-- list of methods -->
85
89
  <% unless @class.method_list.empty? %>
90
+ <!-- list of methods -->
86
91
  <div id="method-list" class="list">
87
92
  <h3>Methods</h3>
88
93
  <% unless @class.class_method_list.empty? %>
@@ -104,8 +109,8 @@
104
109
  </div>
105
110
  <% end %>
106
111
 
107
- <!-- namespace contents -->
108
112
  <% unless @class.non_aliases.empty? %>
113
+ <!-- namespace contents -->
109
114
  <div id="namespace-list" class="list">
110
115
  <h3>Modules and Classes</h3>
111
116
  <table class="classes-modules">
@@ -119,8 +124,8 @@
119
124
  </div>
120
125
  <% end %>
121
126
 
122
- <!-- included modules -->
123
127
  <% unless @class.includes.empty? %>
128
+ <!-- included modules -->
124
129
  <div id="include-list" class="list">
125
130
  <h3>Included Modules</h3>
126
131
  <ul>
@@ -135,8 +140,8 @@
135
140
  </div>
136
141
  <% end %>
137
142
 
138
- <!-- constants -->
139
143
  <% unless @class.constants.empty? %>
144
+ <!-- constants -->
140
145
  <div id="constant-list" class="list">
141
146
  <h3>Constants</h3>
142
147
  <table>
@@ -162,8 +167,8 @@
162
167
  </div>
163
168
  <% end %>
164
169
 
165
- <!-- external aliases -->
166
170
  <% unless @class.external_aliases.empty? %>
171
+ <!-- external aliases -->
167
172
  <div id="external-aliases" class="list">
168
173
  <h3>External Aliases</h3>
169
174
  <table>
@@ -177,8 +182,8 @@
177
182
  </div>
178
183
  <% end %>
179
184
 
180
- <!-- class/module attributes -->
181
185
  <% unless @class.class_attributes.empty? %>
186
+ <!-- class/module attributes -->
182
187
  <div id="class-attributes" class="list">
183
188
  <h3><%= @class.type.capitalize %> Attributes</h3>
184
189
  <table>
@@ -203,8 +208,8 @@
203
208
  </div>
204
209
  <% end %>
205
210
 
206
- <!-- instance attributes -->
207
211
  <% unless @class.instance_attributes.empty? %>
212
+ <!-- instance attributes -->
208
213
  <div id="instance-attributes" class="list">
209
214
  <h3>Instance Attributes</h3>
210
215
  <table>
@@ -267,6 +272,7 @@
267
272
  <% end # @class.methods_by_type.each %>
268
273
 
269
274
  </div> <!-- #documentation -->
275
+ </div> <!-- #main-container -->
270
276
 
271
277
  </body>
272
278
  </html>
@@ -2,18 +2,22 @@
2
2
  <html lang="en">
3
3
  <head>
4
4
  <meta charset="<%= @options.charset %>">
5
- <title>File <%= @file.base_name %></title>
5
+ <title><%= @file.base_name %> &ndash; <%= h @options.title %></title>
6
6
  <link href="<%= @stylesheet_url %>" rel="stylesheet">
7
7
  <link href="https://fonts.googleapis.com/css?family=Noto+Sans" rel="stylesheet">
8
8
  <script src="<%= @rel_prefix %>/scripts/mainFrame.js" type="text/javascript"></script>
9
9
  </head>
10
10
  <body>
11
+ <div id="left-container">
12
+ <iframe id="left-frame" src="<%= @rel_prefix %>/indexes.html"></iframe>
13
+ <div id="resizer"></div>
14
+ </div>
15
+ <div id="main-container">
11
16
  <div id="header">
12
17
  <p class="header-title"><span class="prefix">File</span><span class="name"> <%= @file.base_name %></span></p>
13
18
  <p id="file-info">
14
19
  <span class="displayed">
15
- Path: <%= @file.absolute_name %><br>
16
- Modified: <%= @file.last_modified ? @file.last_modified.strftime('%Y-%m-%d %H:%M:%S') : 'unknown' %>
20
+ Path: <%= @file.absolute_name %>
17
21
  </span>
18
22
  </p>
19
23
  </div>
@@ -54,5 +58,6 @@
54
58
  </div>
55
59
  <% end %>
56
60
  </div>
61
+ </div>
57
62
  </body>
58
63
  </html>
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" height="18px" viewBox="0 0 24 24" width="18px" fill="#000000"><path d="M0 0h24v24H0V0z" fill="none"/><path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41z"/></svg>
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" height="18px" viewBox="0 0 24 24" width="18px" fill="#000000"><path d="M0 0h24v24H0V0z" fill="none"/><path d="M3 18h18v-2H3v2zm0-5h18v-2H3v2zm0-7v2h18V6H3z"/></svg>
@@ -1,11 +1,6 @@
1
1
  <!DOCTYPE html>
2
- <html lang="en">
2
+ <html>
3
3
  <head>
4
- <meta charset="<%= @options.charset %>">
5
- <title><%= h @options.title %></title>
4
+ <meta http-equiv="refresh" content="0; url=<%= @first_page.path %>" />
6
5
  </head>
7
- <frameset cols="20%,*">
8
- <frame name="indexFrame" src="indexes.html">
9
- <frame name="mainFrame" src="<%= @first_page.path %>">
10
- </frameset>
11
6
  </html>
@@ -7,7 +7,7 @@
7
7
  <link href="https://fonts.googleapis.com/css?family=Noto+Sans" rel="stylesheet">
8
8
  <script src="scripts/quicksearch.js" type="text/javascript"></script>
9
9
  <script src="scripts/indexFrame.js" type="text/javascript"></script>
10
- <base target="mainFrame">
10
+ <base target="_parent">
11
11
  </head>
12
12
  <body class="index">
13
13
  <% $stderr.sync = true %>