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 +4 -4
- data/HISTORY.rdoc +15 -0
- data/README.rdoc +17 -16
- data/lib/rdoc/generator/babel.rb +82 -15
- data/lib/rdoc/generator/ruby-lang/class-page.html.erb +15 -9
- data/lib/rdoc/generator/ruby-lang/file-page.html.erb +8 -3
- data/lib/rdoc/generator/ruby-lang/images/close_black_18dp.svg +1 -0
- data/lib/rdoc/generator/ruby-lang/images/menu_black_18dp.svg +1 -0
- data/lib/rdoc/generator/ruby-lang/index.html.erb +2 -7
- data/lib/rdoc/generator/ruby-lang/indexes.html.erb +1 -1
- data/lib/rdoc/generator/ruby-lang/rdoc.css +182 -29
- data/lib/rdoc/generator/ruby-lang/scripts/indexFrame.js +183 -32
- data/lib/rdoc/generator/ruby-lang/scripts/mainFrame.js +202 -33
- data/lib/rdoc/generator/ruby-lang/scripts/quicksearch.js +12 -6
- metadata +6 -4
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 11de5544dfb3dea6db68f549a905deb714ba445bfc02ebff7e2e54f7c4e2cae3
|
4
|
+
data.tar.gz: 7517f06eafd50bf7107645a47e206ab85ad2d04f743baa76d026c4664ef41ec5
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
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
|
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
|
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
|
-
|
30
|
-
|
31
|
-
|
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 '
|
41
|
+
Dir.chdir '/ruby/src'
|
39
42
|
rdoc.options <<
|
40
43
|
'--format' << 'babel' <<
|
41
44
|
'--all'
|
42
|
-
t.title = "Ruby
|
43
|
-
t.rdoc_dir = '
|
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
|
49
|
-
(e.g., <tt>~/.bashrc</tt>):
|
50
|
+
define the RDOCOPT environment variable:
|
50
51
|
|
51
|
-
|
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 >=
|
74
|
-
- RDoc >= 5.0 (may work with >=
|
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-
|
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
|
data/lib/rdoc/generator/babel.rb
CHANGED
@@ -33,7 +33,7 @@ class RDoc::Generator::Babel
|
|
33
33
|
|
34
34
|
RDoc::RDoc.add_generator(self)
|
35
35
|
|
36
|
-
VERSION = '1.
|
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
|
-
|
182
|
-
|
183
|
-
|
184
|
-
|
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
|
-
|
278
|
-
|
279
|
-
|
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
|
-
|
285
|
-
|
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 }
|
288
|
-
|
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 |
|
455
|
-
|
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.
|
5
|
+
<title><%= @class.full_name %> – <%= 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
|
5
|
+
<title><%= @file.base_name %> – <%= 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
|
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
|
2
|
+
<html>
|
3
3
|
<head>
|
4
|
-
<meta
|
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="
|
10
|
+
<base target="_parent">
|
11
11
|
</head>
|
12
12
|
<body class="index">
|
13
13
|
<% $stderr.sync = true %>
|