rdoc-babel 1.2.0 → 1.4.0
Sign up to get free protection for your applications and to get access to all the features.
- 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 %>
|