rdoc 6.17.0 → 7.2.0

data/lib/rdoc/generator/aliki.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'uri'
+
 ##
 # Aliki theme for RDoc documentation
 #
@@ -15,6 +17,30 @@ class RDoc::Generator::Aliki < RDoc::Generator::Darkfish
     @template_dir = Pathname.new(aliki_template_dir)
   end
 
+  ##
+  # Generate documentation. Overrides Darkfish to use Aliki's own search index
+  # instead of the JsonIndex generator.
+
+  def generate
+    setup
+
+    write_style_sheet
+    generate_index
+    generate_class_files
+    generate_file_files
+    generate_table_of_contents
+    write_search_index
+
+    copy_static
+
+  rescue => e
+    debug_msg "%s: %s\n  %s" % [
+      e.class.name, e.message, e.backtrace.join("\n  ")
+    ]
+
+    raise
+  end
+
   ##
   # Copy only the static assets required by the Aliki theme. Unlike Darkfish we
   # don't ship embedded fonts or image sprites, so limit the asset list to keep
@@ -39,4 +65,119 @@ class RDoc::Generator::Aliki < RDoc::Generator::Darkfish
       install_rdoc_static_file @template_dir + path, dst, options
     end
   end
+
+  ##
+  # Build a search index array for Aliki's searcher.
+
+  def build_search_index
+    setup
+
+    index = []
+
+    @classes.each do |klass|
+      next unless klass.display?
+
+      index << build_class_module_entry(klass)
+
+      klass.constants.each do |const|
+        next unless const.display?
+
+        index << build_constant_entry(const, klass)
+      end
+    end
+
+    @methods.each do |method|
+      next unless method.display?
+
+      index << build_method_entry(method)
+    end
+
+    index
+  end
+
+  ##
+  # Write the search index as a JavaScript file
+  # Format: var search_data = { index: [...] }
+  #
+  # We still write to a .js instead of a .json because loading a JSON file triggers CORS check in browsers.
+  # And if we simply inspect the generated pages using file://, which is often the case due to lack of the server mode,
+  # the JSON file will be blocked by the browser.
+
+  def write_search_index
+    debug_msg "Writing Aliki search index"
+
+    index = build_search_index
+
+    FileUtils.mkdir_p 'js' unless @dry_run
+
+    search_index_path = 'js/search_data.js'
+    return if @dry_run
+
+    data = { index: index }
+    File.write search_index_path, "var search_data = #{JSON.generate(data)};"
+  end
+
+  ##
+  # Resolves a URL for use in templates. Absolute URLs are returned unchanged.
+  # Relative URLs are prefixed with rel_prefix to ensure they resolve correctly from any page.
+
+  def resolve_url(rel_prefix, url)
+    uri = URI.parse(url)
+    if uri.absolute?
+      url
+    else
+      "#{rel_prefix}/#{url}"
+    end
+  rescue URI::InvalidURIError
+    "#{rel_prefix}/#{url}"
+  end
+
+  private
+
+  def build_class_module_entry(klass)
+    type = case klass
+           when RDoc::NormalClass then 'class'
+           when RDoc::NormalModule then 'module'
+           else 'class'
+           end
+
+    entry = {
+      name: klass.name,
+      full_name: klass.full_name,
+      type: type,
+      path: klass.path
+    }
+
+    snippet = klass.search_snippet
+    entry[:snippet] = snippet unless snippet.empty?
+    entry
+  end
+
+  def build_method_entry(method)
+    type = method.singleton ? 'class_method' : 'instance_method'
+
+    entry = {
+      name: method.name,
+      full_name: method.full_name,
+      type: type,
+      path: method.path
+    }
+
+    snippet = method.search_snippet
+    entry[:snippet] = snippet unless snippet.empty?
+    entry
+  end
+
+  def build_constant_entry(const, parent)
+    entry = {
+      name: const.name,
+      full_name: "#{parent.full_name}::#{const.name}",
+      type: 'constant',
+      path: parent.path
+    }
+
+    snippet = const.search_snippet
+    entry[:snippet] = snippet unless snippet.empty?
+    entry
+  end
 end

data/lib/rdoc/generator/darkfish.rb

@@ -356,7 +356,9 @@ class RDoc::Generator::Darkfish
 
     current = nil
 
-    @classes.each do |klass|
+    # Document files are generated only for non-alias classes/modules
+    @classes.reject(&:is_alias_for).each do |klass|
+
       current = klass
 
       generate_class klass, template_file

data/lib/rdoc/generator/template/aliki/_footer.rhtml

@@ -6,7 +6,7 @@
       <h3><%= h column_title %></h3>
       <ul>
         <% links.each do |text, url| %>
-        <li><a href="<%= h url %>"><%= h text %></a></li>
+        <li><a href="<%= h resolve_url(rel_prefix, url) %>"><%= h text %></a></li>
         <% end %>
       </ul>
     </div>

data/lib/rdoc/generator/template/aliki/_head.rhtml

@@ -116,22 +116,22 @@
 ></script>
 
 <script
-  src="<%= h asset_rel_prefix %>/js/navigation.js?v=<%= h RDoc::VERSION %>"
+  src="<%= h asset_rel_prefix %>/js/search_navigation.js?v=<%= h RDoc::VERSION %>"
   defer
 ></script>
 
 <script
-  src="<%= h asset_rel_prefix %>/js/search.js?v=<%= h RDoc::VERSION %>"
+  src="<%= h asset_rel_prefix %>/js/search_data.js?v=<%= h RDoc::VERSION %>"
   defer
 ></script>
 
 <script
-  src="<%= h asset_rel_prefix %>/js/search_index.js?v=<%= h RDoc::VERSION %>"
+  src="<%= h asset_rel_prefix %>/js/search_ranker.js?v=<%= h RDoc::VERSION %>"
   defer
 ></script>
 
 <script
-  src="<%= h asset_rel_prefix %>/js/searcher.js?v=<%= h RDoc::VERSION %>"
+  src="<%= h asset_rel_prefix %>/js/search_controller.js?v=<%= h RDoc::VERSION %>"
   defer
 ></script>
 
@@ -140,6 +140,11 @@
   defer
 ></script>
 
+<script
+  src="<%= h asset_rel_prefix %>/js/bash_highlighter.js?v=<%= h RDoc::VERSION %>"
+  defer
+></script>
+
 <script
   src="<%= h asset_rel_prefix %>/js/aliki.js?v=<%= h RDoc::VERSION %>"
   defer

data/lib/rdoc/generator/template/aliki/_header.rhtml

@@ -7,13 +7,13 @@
   <div class="navbar-search navbar-search-desktop" role="search">
     <form action="#" method="get" accept-charset="utf-8">
       <input id="search-field" role="combobox" aria-label="Search"
-             aria-autocomplete="list" aria-controls="search-results"
+             aria-autocomplete="list" aria-controls="search-results-desktop"
              type="text" name="search" placeholder="Search (/) for a class, method..."
              spellcheck="false" autocomplete="off"
              title="Type to search, Up and Down to navigate, Enter to load">
-      <ul id="search-results" aria-label="Search Results"
+      <ul id="search-results-desktop" aria-label="Search Results"
           aria-busy="false" aria-expanded="false"
-          aria-atomic="false" class="initially-hidden"></ul>
+          aria-atomic="false" class="initially-hidden search-results"></ul>
     </form>
   </div>
 
@@ -47,7 +47,7 @@
     <div class="search-modal-body">
       <ul id="search-results-mobile" aria-label="Search Results"
           aria-busy="false" aria-expanded="false"
-          aria-atomic="false" class="search-modal-results initially-hidden"></ul>
+          aria-atomic="false" class="search-results search-modal-results initially-hidden"></ul>
       <div class="search-modal-empty">
         <p>No recent searches</p>
       </div>

data/lib/rdoc/generator/template/aliki/_sidebar_pages.rhtml

@@ -35,7 +35,7 @@
                 <%= h f.page_name %>
               </a>
             </li>
-            <%- next %>
+            <%- next -%>
           <%- end %>
 
           <li>

data/lib/rdoc/generator/template/aliki/_sidebar_search.rhtml

@@ -2,14 +2,14 @@
   <form action="#" method="get" accept-charset="utf-8">
     <div id="search-field-wrapper">
       <input id="search-field" role="combobox" aria-label="Search"
-             aria-autocomplete="list" aria-controls="search-results"
+             aria-autocomplete="list" aria-controls="search-results-desktop"
              type="text" name="search" placeholder="Search (/) for a class, method, ..." spellcheck="false"
              autocomplete="off"
              title="Type to search, Up and Down to navigate, Enter to load">
     </div>
 
-    <ul id="search-results" aria-label="Search Results"
+    <ul id="search-results-desktop" aria-label="Search Results"
         aria-busy="false" aria-expanded="false"
-        aria-atomic="false" class="initially-hidden"></ul>
+        aria-atomic="false" class="initially-hidden search-results"></ul>
   </form>
 </div>

data/lib/rdoc/generator/template/aliki/class.rhtml

@@ -3,7 +3,7 @@
 <%= render '_header.rhtml' %>
 <%= render '_sidebar_toggle.rhtml' %>
 
-<nav id="navigation" role="navigation">
+<nav id="navigation" role="navigation" hidden>
   <%= render '_sidebar_pages.rhtml' %>
   <%= render '_sidebar_sections.rhtml' %>
   <%= render '_sidebar_ancestors.rhtml' %>
@@ -29,6 +29,7 @@
     </ol>
   <% end %>
 
+  <span id="<%= h klass.legacy_aref %>" class="legacy-anchor"></span>
   <h1 id="<%= h klass.aref %>" class="anchor-link <%= klass.type %>">
     <%= klass.type %> <%= klass.full_name %>
   </h1>
@@ -38,10 +39,11 @@
   </section>
 
   <%- klass.each_section do |section, constants, attributes| %>
-  <section id="<%= section.aref %>" class="documentation-section anchor-link">
+  <span id="<%= section.legacy_aref %>" class="legacy-anchor"></span>
+  <section class="documentation-section anchor-link">
     <%- if section.title then %>
     <header class="documentation-section-title">
-      <h2>
+      <h2 id="<%= section.aref %>">
         <a href="#<%= section.aref %>"><%= section.title %></a>
       </h2>
     </header>
@@ -56,7 +58,7 @@
     <%- unless constants.empty? then %>
     <section class="constants-list">
       <header>
-        <h3 id="constants"><a href="#constants">Constants</a></h3>
+        <h3 id="<%= section.aref %>-constants"><a href="#<%= section.aref %>-constants">Constants</a></h3>
       </header>
       <dl>
       <%- constants.each do |const| %>
@@ -81,7 +83,7 @@
     <%- unless attributes.empty? then %>
     <section class="attribute-method-details method-section">
       <header>
-        <h3 id="attributes"><a href="#attributes">Attributes</a></h3>
+        <h3 id="<%= section.aref %>-attributes"><a href="#<%= section.aref %>-attributes">Attributes</a></h3>
       </header>
 
       <%- attributes.each do |attrib| %>
@@ -110,13 +112,13 @@
     </section>
     <%- end %>
 
-    <%- klass.methods_by_type(section).each do |type, visibilities|
-       next if visibilities.empty?
-       visibilities.each do |visibility, methods|
-         next if methods.empty? %>
+    <%- klass.methods_by_type(section).each do |type, visibilities| %>
+    <%- next if visibilities.empty? %>
+    <%- visibilities.each do |visibility, methods| %>
+    <%- next if methods.empty? %>
      <section id="<%= visibility %>-<%= type %>-<%= section.aref %>-method-details" class="method-section anchor-link">
        <header>
-         <h3 id="<%= visibility %>-<%= type %>-methods"><a href="#<%= visibility %>-<%= type %>-methods"><%= visibility.to_s.capitalize %> <%= type.capitalize %> Methods</a></h3>
+         <h3 id="<%= visibility %>-<%= type %>-<%= section.aref %>-methods"><a href="#<%= visibility %>-<%= type %>-<%= section.aref %>-methods"><%= visibility.to_s.capitalize %> <%= type.capitalize %> Methods</a></h3>
        </header>
 
     <%- methods.each do |method| %>
@@ -156,15 +158,13 @@
               <summary>Source</summary>
             </details>
           </div>
+          <div class="method-source-code" id="<%= method.html_name %>-source">
+            <pre class="<%= method.source_language %>"><%= method.markup_code %></pre>
+          </div>
         <%- end %>
 
         <%- unless method.skip_description? then %>
         <div class="method-description">
-          <%- if method.token_stream then %>
-          <div class="method-source-code" id="<%= method.html_name %>-source">
-            <pre class="<%= method.source_language %>" data-language="<%= method.source_language %>"><%= method.markup_code %></pre>
-          </div>
-          <%- end %>
           <%- if method.mixin_from then %>
             <div class="mixin-from">
               <%= method.singleton ? "Extended" : "Included" %> from <a href="<%= klass.aref_to(method.mixin_from.path) %>"><%= method.mixin_from.full_name %></a>
@@ -208,8 +208,8 @@
 
     <%- end %>
     </section>
-  <%- end
-     end %>
+  <%- end %>
+  <%- end %>
   </section>
 <%- end %>
 </main>