rdoc-babel 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55f4e3e723fcdd5967ec422747a0de38dba85db8c8a7e3592232e67346b3aa92
-  data.tar.gz: '0855f9b0383d9b91ada6369e90436d8d9532d4116f8d2fb29369c3bdb1e13864'
+  metadata.gz: 11de5544dfb3dea6db68f549a905deb714ba445bfc02ebff7e2e54f7c4e2cae3
+  data.tar.gz: 7517f06eafd50bf7107645a47e206ab85ad2d04f743baa76d026c4664ef41ec5
 SHA512:
-  metadata.gz: 77548381b3e7ed0f445016295b94eb7498f8d84686fa5df90319ec72138d4ab12d07f2e872bae59b54e4acc79506c85e2f39727dc5e20809f9852ebdffe70ba2
-  data.tar.gz: d3a6fd0e292026ece7ceefdd68f6654e7ebef7c6c3aca5d41283927e830c13679ac9fa198980e26c2b52b86452bf00df58d563f61e50e8f4d057cb5cc9537ad0
+  metadata.gz: 9afb98e8a4e926772fc79b43b741222f1d7ceaf960f1f7157b5c4ca78137031d3eaf6f586851e7cfdac2df921850504f5e8414c7a1aca9fae67f7d825b2fa027
+  data.tar.gz: dbbe9dee9014d525008d60d73ead16f53258125d28712c8ccf2fecf5266e7960707d6c34b71f3c95c684c30c604e91f95d2b4258fe88c8ca9d93056fc89fa18b

data/HISTORY.rdoc

@@ -1,3 +1,18 @@
+=== 1.4.0
+
+* add a TOC button on the top right
+* fix initial sizing in the left pane
+* fix too wide <pre> sections
+
+=== 1.3.0
+
+* switch from frameset to iframe
+* highlight the current file/class/method in the left frame
+
+=== 1.2.1
+
+* filter: only search in link text (skip class/method type)
+
 === 1.2.0
 
 * add resizing of indexes in left frame

data/README.rdoc

@@ -16,39 +16,40 @@ and to contribute alternate templates or style sheets.
 - Dual-frame output, with indexes on the left.
 - Search boxes for classes and methods.
 - Links to undocumented classes/methods are grayed.
-- Highlights target methods, attributes and constants.
+- Highlights the current file/class/method in the left frame.
+- Highlights the target method, attribute or constant in the main frame.
 - Adds links to ancestor methods/attributes.
 - Borrows some ideas (and one icon) from Darkfish.
-- Tested on Firefox 3.5 & 5, Chrome 9 & 12, Safari 4 & 5.
+- Tested on Firefox 125.<br>
+  If using the <tt>file://</tt> protocol, the "same origin policy" for local files must be turned off:<br>
+  <tt>about:config</tt> > <tt>security.fileuri.strict_origin_policy = false</tt>
 
 == Synopsis
 
 To output documentation formatted by Babel, use the <tt>--format/-f</tt>
-RDoc switch. For instance, to generate the documentation for Ruby core:
+RDoc switch. For instance, to generate the documentation for Ruby core and stdlib:
 
-  $ gem install rdoc-babel
-  $ cd ~/.rvm/src/ruby-1.8.7-p302
-  $ rdoc -f babel -a -t "Ruby 1.8.7 Core" -o ~/docs/ruby_core_187 *.c
+  > gem install rdoc-babel
+  > cd /ruby/src
+  > rdoc -f babel -a -t "Ruby Core + Stdlib" -o /docs/ruby-core
 
 Using rake:
 
   require 'rdoc/task'
 
   RDoc::Task.new do |t|
-    Dir.chdir '~/.rvm/src/ruby-1.9.2-p0'
+    Dir.chdir '/ruby/src'
     rdoc.options <<
       '--format' << 'babel' <<
       '--all'
-    t.title = "Ruby 1.9.2 Core"
-    t.rdoc_dir = '~/docs/ruby_core_192'
-    t.rdoc_files.concat Dir['*.c']
+    t.title = "Ruby Core + Stdlib"
+    t.rdoc_dir = '/docs/ruby-core'
   end
 
 To make Babel the default format when generating RDoc documentation,
-define the RDOCOPT environment variable in the appropriate file
-(e.g., <tt>~/.bashrc</tt>):
+define the RDOCOPT environment variable:
 
-  export RDOCOPT="--format babel"
+  RDOCOPT="--format babel"
 
 == Specific options
 
@@ -70,8 +71,8 @@ Babel supports specific options in addition to the standard RDoc options:
 
 == Requirements
 
-- Ruby >= 2.3.0 (may work with >= 1.9.3, but untested)
-- RDoc >= 5.0 (may work with >= 4.0, but untested)
+- Ruby >= 3.1.0 (may work with >= 2.5.0, but untested)
+- RDoc >= 6.5.0 (may work with >= 5.0, but untested)
 
 == Installation
 
@@ -81,7 +82,7 @@ Babel supports specific options in addition to the standard RDoc options:
 
 (The MIT License)
 
-Copyright (c) 2010-2020 Thierry Lambert
+Copyright (c) 2010-2024 Thierry Lambert
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/lib/rdoc/generator/babel.rb

@@ -33,7 +33,7 @@ class RDoc::Generator::Babel
 
   RDoc::RDoc.add_generator(self)
 
-  VERSION = '1.2.0'
+  VERSION = '1.4.0'
   DESCRIPTION = 'Alternate HTML documentation'
 
   include ERB::Util
@@ -157,6 +157,25 @@ class RDoc::Generator::Babel
 
   def generate
 
+    # rdoc bug fix: public class/module methods appear as external_aliases (unresolved aliases)
+
+    @store.all_classes_and_modules.each do |cm|
+      next if cm.external_aliases.empty?
+      class_level_names = cm.method_list.select { |m| m.type == 'class' }.map(&:name)
+      cm.external_aliases.dup.each do |a|
+        cm.external_aliases.delete a if class_level_names.include?(a.name)
+      end
+    end
+
+    # other bug fix: method aliases with singleton mismatch
+
+    @store.all_classes_and_modules.each do |cm|
+      cm.class_method_list.each do |m|
+        m.is_alias_for.singleton = true if m.is_alias_for
+        m.aliases.each { |a| a.singleton = true }
+      end
+    end
+
     # set instance variables
 
     @output_dir = Pathname.new(@options.op_dir).expand_path(@source_dir)
@@ -178,11 +197,25 @@ class RDoc::Generator::Babel
         @simple_files
       end
 
-    @main_file = @options.main_page && @all_files.find { |f| f.full_name == @options.main_page }
-    if @main_file
-      unless @files_to_display.find { |f| f.full_name == @options.main_page }
-        @files_to_display.unshift @main_file
+    if @options.main_page
+      # look for a TopLevel matching the main page
+      @main_page = @all_files.find { |f| f.full_name == @options.main_page }
+      if @main_page
+        # TODO are there cases where main_page = 'README' for 'lib/README'?
+        unless @files_to_display.find { |f| f.full_name == @options.main_page }
+          @files_to_display.unshift @main_page
+        end
+      # look for a class/module with that name
+      else
+        match = @unique_classes_and_modules.find { |cm| cm.full_name == @options.main_page }
+        if match
+          @main_page = match
+        else
+          warn "no such page: --main #{@options.main_page}"
+        end
       end
+    else
+      @main_page = nil
     end
 
     # write the output
@@ -263,7 +296,7 @@ class RDoc::Generator::Babel
   # Returns the first +Context+ object to display in the main frame.
   # This is, in order:
   # - The file designated by the +main_page+ option,
-  #   if there is a +TopLevel+ with that name.
+  #   if there is a +TopLevel+ or class/module with that name.
   # - The first simple file that contains a comment
   #   (in the order given on the command line).
   # - The first class or module that contains a comment.
@@ -274,19 +307,30 @@ class RDoc::Generator::Babel
   # - The first file.
 
   def first_page
-    # TODO are there cases where main_page = 'README' for 'lib/README'?
-    if @options.main_page && (main_file = @all_files.find { |f| f.full_name == @options.main_page })
-      main_file
+    if @main_page
+      debug_msg "main as --main: #{@main_page}"
+      @main_page
     elsif (file = @simple_files.first)
+      debug_msg "main as first simple file: #{file}"
       file
     elsif (cm = @unique_classes_and_modules.find { |k| !k.comment.empty? })
+      debug_msg "main as first module/class with comment: #{cm}"
       cm
-    elsif (file = @files_with_comment.first)
-      file
+    # this is not a simple file, so currently not displayed in files
+    # elsif (file = @files_with_comment.first)
+    #   debug_msg "main as first file with comment: #{file}"
+    #   file
     elsif !@unique_classes_and_modules.empty?
-      @unique_classes_and_modules.find { |k| k.any_content } or
-        @unique_classes_and_modules.first
+      cm = @unique_classes_and_modules.find { |k| k.any_content }
+      if cm
+        debug_msg "main as first module/class with any content: #{cm}"
+      else
+        debug_msg "main as first module/class (no content): #{cm}"
+        cm = @unique_classes_and_modules.first
+      end
+      cm
     else
+      debug_msg "main as first file: #{cm}"
       @all_files.first
     end
   end
@@ -450,9 +494,32 @@ protected
 
     return if @options.dry_run
 
+    # fix file cross-references
+    # rdoc:ref handling by RDoc requires that files and classes are stored in the
+    # root output directory, while we have files and classes in separate subdirectories
+    output.gsub!(/<a (.*?)\bhref="(.+?)"/) do |match|
+      atts = $1
+      href = $2
+      next match if href[0] == '#'
+      path, id = href.split('#')
+      # in classes/OptionParser.html:
+      # we find for instance <a href="optparse/tutorial_rdoc.html">Tutorial</a>
+      # which matches files/doc/optparse/tutorial_rdoc.html
+      matches = @all_files.select do |f|
+        f.path.end_with?(path) && f.path != path
+      end
+      next match if matches.empty?
+      # we replace optparse/tutorial_rdoc.html by ../files/doc/optparse/tutorial_rdoc.html
+      f = matches.first
+      actual = Pathname.new(f.path).expand_path(@output_dir).relative_path_from(outfile.dirname).to_s
+      next match if actual == path
+      actual << '#' << id if id
+      %(<a #{atts}href="#{actual}")
+    end
+
     outfile.dirname.mkpath
-    outfile.open('w', 0644) do |ofh|
-      ofh.print(output)
+    outfile.open('w', 0644) do |io|
+      io.print(output)
     end
 
   end

data/lib/rdoc/generator/ruby-lang/class-page.html.erb

@@ -2,13 +2,18 @@
 <html lang="en">
 <head>
   <meta charset="<%= @options.charset %>">
-  <title><%= @class.type.capitalize %> <%= @class.full_name %></title>
+  <title><%= @class.full_name %> &ndash; <%= h @options.title %></title>
   <link href="<%= @stylesheet_url %>" rel="stylesheet">
   <link href="https://fonts.googleapis.com/css?family=Noto+Sans" rel="stylesheet">
   <script src="<%= @rel_prefix %>/scripts/mainFrame.js" type="text/javascript"></script>
 </head>
 <body>
 
+<div id="left-container">
+<iframe id="left-frame" src="<%= @rel_prefix %>/indexes.html"></iframe>
+<div id="resizer"></div>
+</div>
+<div id="main-container">
 <div id="header">
   <p class="header-title">
     <span class="prefix"><%= @class.type.capitalize %></span><span class="name"> <%= @class.full_name %></span>
@@ -69,8 +74,8 @@
 
 <%= @class.description %>
 
-<!-- class/module aliases -->
 <% unless @class.aliases.empty? %>
+<!-- class/module aliases -->
 <div id="class-aliases" class="list">
   <h3><%= @class.type.capitalize %> Aliases</h3>
   <ul>
@@ -81,8 +86,8 @@
 </div>
 <% end %>
 
-<!-- list of methods -->
 <% unless @class.method_list.empty? %>
+<!-- list of methods -->
 <div id="method-list" class="list">
   <h3>Methods</h3>
   <% unless @class.class_method_list.empty? %>
@@ -104,8 +109,8 @@
 </div>
 <% end %>
 
-<!-- namespace contents -->
 <% unless @class.non_aliases.empty? %>
+<!-- namespace contents -->
 <div id="namespace-list" class="list">
   <h3>Modules and Classes</h3>
   <table class="classes-modules">
@@ -119,8 +124,8 @@
 </div>
 <% end %>
 
-<!-- included modules -->
 <% unless @class.includes.empty? %>
+<!-- included modules -->
 <div id="include-list" class="list">
   <h3>Included Modules</h3>
   <ul>
@@ -135,8 +140,8 @@
 </div>
 <% end %>
 
-<!-- constants -->
 <% unless @class.constants.empty? %>
+<!-- constants -->
 <div id="constant-list" class="list">
   <h3>Constants</h3>
   <table>
@@ -162,8 +167,8 @@
 </div>
 <% end %>
 
-<!-- external aliases -->
 <% unless @class.external_aliases.empty? %>
+<!-- external aliases -->
 <div id="external-aliases" class="list">
   <h3>External Aliases</h3>
   <table>
@@ -177,8 +182,8 @@
 </div>
 <% end %>
 
-<!-- class/module attributes -->
 <% unless @class.class_attributes.empty? %>
+<!-- class/module attributes -->
 <div id="class-attributes" class="list">
   <h3><%= @class.type.capitalize %> Attributes</h3>
   <table>
@@ -203,8 +208,8 @@
 </div>
 <% end %>
 
-<!-- instance attributes -->
 <% unless @class.instance_attributes.empty? %>
+<!-- instance attributes -->
 <div id="instance-attributes" class="list">
   <h3>Instance Attributes</h3>
   <table>
@@ -267,6 +272,7 @@
 <% end # @class.methods_by_type.each %>
 
 </div> <!-- #documentation -->
+</div> <!-- #main-container -->
 
 </body>
 </html>

data/lib/rdoc/generator/ruby-lang/file-page.html.erb

@@ -2,18 +2,22 @@
 <html lang="en">
 <head>
   <meta charset="<%= @options.charset %>">
-  <title>File <%= @file.base_name %></title>
+  <title><%= @file.base_name %> &ndash; <%= h @options.title %></title>
   <link href="<%= @stylesheet_url %>" rel="stylesheet">
   <link href="https://fonts.googleapis.com/css?family=Noto+Sans" rel="stylesheet">
   <script src="<%= @rel_prefix %>/scripts/mainFrame.js" type="text/javascript"></script>
 </head>
 <body>
+<div id="left-container">
+<iframe id="left-frame" src="<%= @rel_prefix %>/indexes.html"></iframe>
+<div id="resizer"></div>
+</div>
+<div id="main-container">
 <div id="header">
   <p class="header-title"><span class="prefix">File</span><span class="name"> <%= @file.base_name %></span></p>
   <p id="file-info">
     <span class="displayed">
-      Path: <%= @file.absolute_name %><br>
-      Modified: <%= @file.last_modified ? @file.last_modified.strftime('%Y-%m-%d %H:%M:%S') : 'unknown' %>
+      Path: <%= @file.absolute_name %>
     </span>
   </p>
 </div>
@@ -54,5 +58,6 @@
   </div>
 <% end %>
 </div>
+</div>
 </body>
 </html>

data/lib/rdoc/generator/ruby-lang/images/close_black_18dp.svg

@@ -0,0 +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>

data/lib/rdoc/generator/ruby-lang/images/menu_black_18dp.svg

@@ -0,0 +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>

data/lib/rdoc/generator/ruby-lang/index.html.erb

@@ -1,11 +1,6 @@
 <!DOCTYPE html>
-<html lang="en">
+<html>
 <head>
-  <meta charset="<%= @options.charset %>">
-  <title><%= h @options.title %></title>
+  <meta http-equiv="refresh" content="0; url=<%= @first_page.path %>" />
 </head>
-<frameset cols="20%,*">
-  <frame name="indexFrame" src="indexes.html">
-  <frame name="mainFrame" src="<%= @first_page.path %>">
-</frameset>
 </html>

data/lib/rdoc/generator/ruby-lang/indexes.html.erb

@@ -7,7 +7,7 @@
   <link href="https://fonts.googleapis.com/css?family=Noto+Sans" rel="stylesheet">
   <script src="scripts/quicksearch.js" type="text/javascript"></script>
   <script src="scripts/indexFrame.js" type="text/javascript"></script>
-  <base target="mainFrame">
+  <base target="_parent">
 </head>
 <body class="index">
 <% $stderr.sync = true %>