rdoc 6.15.1 → 7.0.3

data/lib/rdoc/generator/template/aliki/js/search_ranker.js

@@ -0,0 +1,239 @@
+/**
+ * Aliki Search Implementation
+ *
+ * Search algorithm with the following priorities:
+ * 1. Exact full_name match always wins (for namespace/method queries)
+ * 2. Exact name match gets high priority
+ * 3. Match types:
+ *    - Namespace queries (::) and method queries (# or .) match against full_name
+ *    - Regular queries match against unqualified name
+ *    - Prefix (10000) > substring (5000) > fuzzy (1000)
+ * 4. First character determines type priority:
+ *    - Starts with lowercase: methods first
+ *    - Starts with uppercase: classes/modules/constants first
+ * 5. Within same type priority:
+ *    - Unqualified match > qualified match
+ *    - Shorter name > longer name
+ * 6. Class methods > instance methods
+ * 7. Result limit: 30
+ * 8. Minimum query length: 1 character
+ */
+
+var MAX_RESULTS = 30;
+var MIN_QUERY_LENGTH = 1;
+
+/*
+ * Scoring constants - organized in tiers where each tier dominates lower tiers.
+ * This ensures match type always beats type priority, etc.
+ *
+ * Tier 0: Exact matches (immediate return)
+ * Tier 1: Match type (prefix > substring > fuzzy)
+ * Tier 2: Exact name bonus
+ * Tier 3: Type priority (method vs class based on query case)
+ * Tier 4: Minor bonuses (top-level, class method, name length)
+ */
+var SCORE_EXACT_FULL_NAME = 1000000;  // Tier 0: Query exactly matches full_name
+var SCORE_MATCH_PREFIX    = 10000;    // Tier 1: Query is prefix of name
+var SCORE_MATCH_SUBSTRING = 5000;     // Tier 1: Query is substring of name
+var SCORE_MATCH_FUZZY     = 1000;     // Tier 1: Query chars appear in order
+var SCORE_EXACT_NAME      = 500;      // Tier 2: Name exactly equals query
+var SCORE_TYPE_PRIORITY   = 100;      // Tier 3: Preferred type (method/class)
+var SCORE_TOP_LEVEL       = 50;       // Tier 4: Top-level over namespaced
+var SCORE_CLASS_METHOD    = 10;       // Tier 4: Class method over instance method
+
+/**
+ * Check if all characters in query appear in order in target
+ * e.g., "addalias" fuzzy matches "add_foo_alias"
+ */
+function fuzzyMatch(target, query) {
+  var ti = 0;
+  for (var qi = 0; qi < query.length; qi++) {
+    ti = target.indexOf(query[qi], ti);
+    if (ti === -1) return false;
+    ti++;
+  }
+  return true;
+}
+
+/**
+ * Parse and normalize a search query
+ * @param {string} query - The raw search query
+ * @returns {Object} Parsed query with normalized form and flags
+ */
+function parseQuery(query) {
+  // Lowercase for case-insensitive matching (so "hash" finds both Hash class and #hash methods)
+  var normalized = query.toLowerCase();
+  var isNamespaceQuery = query.includes('::');
+  var isMethodQuery = query.includes('#') || query.includes('.');
+
+  // Normalize . to :: (RDoc uses :: for class methods in full_name)
+  if (query.includes('.')) {
+    normalized = normalized.replace(/\./g, '::');
+  }
+
+  return {
+    original: query,
+    normalized: normalized,
+    isNamespaceQuery: isNamespaceQuery,
+    isMethodQuery: isMethodQuery,
+    // Namespace and method queries match against full_name instead of name
+    matchesFullName: isNamespaceQuery || isMethodQuery,
+    // If query starts with lowercase, prioritize methods; otherwise prioritize classes/modules/constants
+    prioritizeMethod: !/^[A-Z]/.test(query)
+  };
+}
+
+/**
+ * Main search function
+ * @param {string} query - The search query
+ * @param {Array} index - The search index to search in
+ * @returns {Array} Array of matching entries, sorted by relevance
+ */
+function search(query, index) {
+  if (!query || query.length < MIN_QUERY_LENGTH) {
+    return [];
+  }
+
+  var q = parseQuery(query);
+  var results = [];
+
+  for (var i = 0; i < index.length; i++) {
+    var entry = index[i];
+    var score = computeScore(entry, q);
+
+    if (score !== null) {
+      results.push({ entry: entry, score: score });
+    }
+  }
+
+  results.sort(function(a, b) {
+    return b.score - a.score;
+  });
+
+  return results.slice(0, MAX_RESULTS).map(function(r) {
+    return r.entry;
+  });
+}
+
+/**
+ * Compute the relevance score for an entry
+ * @param {Object} entry - The search index entry
+ * @param {Object} q - Parsed query from parseQuery()
+ * @returns {number|null} Score or null if no match
+ */
+function computeScore(entry, q) {
+  var name = entry.name;
+  var fullName = entry.full_name;
+  var type = entry.type;
+
+  var nameLower = name.toLowerCase();
+  var fullNameLower = fullName.toLowerCase();
+
+  // Exact full_name match (e.g., "Array#filter" matches Array#filter)
+  if (q.matchesFullName && fullNameLower === q.normalized) {
+    return SCORE_EXACT_FULL_NAME;
+  }
+
+  var matchScore = 0;
+  var target = q.matchesFullName ? fullNameLower : nameLower;
+
+  if (target.startsWith(q.normalized)) {
+    matchScore = SCORE_MATCH_PREFIX;     // Prefix (e.g., "Arr" matches "Array")
+  } else if (target.includes(q.normalized)) {
+    matchScore = SCORE_MATCH_SUBSTRING;  // Substring (e.g., "ray" matches "Array")
+  } else if (fuzzyMatch(target, q.normalized)) {
+    matchScore = SCORE_MATCH_FUZZY;      // Fuzzy (e.g., "addalias" matches "add_foo_alias")
+  } else {
+    return null;
+  }
+
+  var score = matchScore;
+  var isMethod = (type === 'instance_method' || type === 'class_method');
+
+  if (q.prioritizeMethod ? isMethod : !isMethod) {
+    score += SCORE_TYPE_PRIORITY;
+  }
+
+  if (type === 'class_method') score += SCORE_CLASS_METHOD;
+  if (name === fullName) score += SCORE_TOP_LEVEL;  // Top-level (Hash) > namespaced (Foo::Hash)
+  if (nameLower === q.normalized) score += SCORE_EXACT_NAME;  // Exact name match
+  score -= name.length;
+
+  return score;
+}
+
+/**
+ * SearchRanker class for compatibility with the Search UI
+ * Provides ready() and find() interface
+ */
+function SearchRanker(index) {
+  this.index = index;
+  this.handlers = [];
+}
+
+SearchRanker.prototype.ready = function(fn) {
+  this.handlers.push(fn);
+};
+
+SearchRanker.prototype.find = function(query) {
+  var q = parseQuery(query);
+  var rawResults = search(query, this.index);
+  var results = rawResults.map(function(entry) {
+    return formatResult(entry, q);
+  });
+
+  var _this = this;
+  this.handlers.forEach(function(fn) {
+    fn.call(_this, results, true);
+  });
+};
+
+/**
+ * Format a search result entry for display
+ */
+function formatResult(entry, q) {
+  var result = {
+    title: highlightMatch(entry.full_name, q),
+    path: entry.path,
+    type: entry.type
+  };
+
+  if (entry.snippet) {
+    result.snippet = entry.snippet;
+  }
+
+  return result;
+}
+
+/**
+ * Add highlight markers (\u0001 and \u0002) to matching portions of text
+ * @param {string} text - The text to highlight
+ * @param {Object} q - Parsed query from parseQuery()
+ */
+function highlightMatch(text, q) {
+  if (!text || !q) return text;
+
+  var textLower = text.toLowerCase();
+  var query = q.normalized;
+
+  // Try contiguous match first (prefix or substring)
+  var matchIndex = textLower.indexOf(query);
+  if (matchIndex !== -1) {
+    return text.substring(0, matchIndex) +
+      '\u0001' + text.substring(matchIndex, matchIndex + query.length) + '\u0002' +
+      text.substring(matchIndex + query.length);
+  }
+
+  // Fall back to fuzzy highlight (highlight each matched character)
+  var result = '';
+  var ti = 0;
+  for (var qi = 0; qi < query.length; qi++) {
+    var charIndex = textLower.indexOf(query[qi], ti);
+    if (charIndex === -1) return text;
+    result += text.substring(ti, charIndex);
+    result += '\u0001' + text[charIndex] + '\u0002';
+    ti = charIndex + 1;
+  }
+  result += text.substring(ti);
+  return result;
+}

data/lib/rdoc/generator/template/aliki/js/theme-toggle.js

@@ -0,0 +1,112 @@
+(function() {
+  'use strict';
+
+  const STORAGE_KEY = 'rdoc-theme';
+  const THEME_LIGHT = 'light';
+  const THEME_DARK = 'dark';
+
+  /**
+   * Get the user's theme preference
+   * Priority: localStorage > system preference > light (default)
+   */
+  function getThemePreference() {
+    // Check localStorage first
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored === THEME_LIGHT || stored === THEME_DARK) {
+      return stored;
+    }
+
+    // Check system preference
+    if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {
+      return THEME_DARK;
+    }
+
+    return THEME_LIGHT;
+  }
+
+  /**
+   * Apply theme to document
+   */
+  function applyTheme(theme) {
+    document.documentElement.setAttribute('data-theme', theme);
+    localStorage.setItem(STORAGE_KEY, theme);
+
+    // Update toggle button icon
+    const toggleBtn = document.getElementById('theme-toggle');
+    if (toggleBtn) {
+      const icon = toggleBtn.querySelector('.theme-toggle-icon');
+      if (icon) {
+        icon.textContent = theme === THEME_DARK ? '☀️' : '🌙';
+      }
+      toggleBtn.setAttribute('aria-label',
+        theme === THEME_DARK ? 'Switch to light mode' : 'Switch to dark mode'
+      );
+    }
+  }
+
+  /**
+   * Toggle between light and dark themes
+   */
+  function toggleTheme() {
+    const currentTheme = document.documentElement.getAttribute('data-theme') || THEME_LIGHT;
+    const newTheme = currentTheme === THEME_LIGHT ? THEME_DARK : THEME_LIGHT;
+    applyTheme(newTheme);
+
+    // Announce to screen readers
+    announceThemeChange(newTheme);
+  }
+
+  /**
+   * Announce theme change to screen readers
+   */
+  function announceThemeChange(theme) {
+    const announcement = document.createElement('div');
+    announcement.setAttribute('role', 'status');
+    announcement.setAttribute('aria-live', 'polite');
+    announcement.className = 'sr-only';
+    announcement.textContent = `Switched to ${theme} mode`;
+    document.body.appendChild(announcement);
+
+    // Remove after announcement
+    setTimeout(() => {
+      document.body.removeChild(announcement);
+    }, 1000);
+  }
+
+  /**
+   * Initialize theme on page load
+   */
+  function initTheme() {
+    // Apply theme immediately to prevent flash
+    const theme = getThemePreference();
+    applyTheme(theme);
+
+    // Set up toggle button listener
+    const toggleBtn = document.getElementById('theme-toggle');
+    if (toggleBtn) {
+      toggleBtn.addEventListener('click', toggleTheme);
+    }
+
+    // Listen for system theme changes
+    if (window.matchMedia) {
+      window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
+        // Only auto-switch if user hasn't manually set a preference
+        const stored = localStorage.getItem(STORAGE_KEY);
+        if (!stored) {
+          applyTheme(e.matches ? THEME_DARK : THEME_LIGHT);
+        }
+      });
+    }
+  }
+
+  // Initialize immediately (before DOMContentLoaded to prevent flash)
+  if (document.readyState === 'loading') {
+    // Apply theme as early as possible
+    const theme = getThemePreference();
+    document.documentElement.setAttribute('data-theme', theme);
+
+    document.addEventListener('DOMContentLoaded', initTheme);
+  } else {
+    initTheme();
+  }
+})();

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

@@ -0,0 +1,18 @@
+<body role="document" class="file has-toc">
+<%= render '_icons.rhtml' %>
+<%= render '_header.rhtml' %>
+<%= render '_sidebar_toggle.rhtml' %>
+
+<nav id="navigation" role="navigation" hidden>
+  <%= render '_sidebar_pages.rhtml' %>
+  <%= render '_sidebar_classes.rhtml' %>
+</nav>
+
+<main role="main" aria-label="Page <%= h file.full_name %>">
+<%= file.description %>
+</main>
+
+<%= render '_aside_toc.rhtml' %>
+
+<%= render '_footer.rhtml' %>
+</body>

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

@@ -0,0 +1,14 @@
+<body role="document">
+<%= render '_sidebar_toggle.rhtml' %>
+
+<nav id="navigation" role="navigation" hidden>
+  <%= render '_sidebar_pages.rhtml' %>
+  <%= render '_sidebar_classes.rhtml' %>
+</nav>
+
+<main role="main">
+  <h1>Not Found</h1>
+
+  <p><%= message %></p>
+</main>
+</body>

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

@@ -0,0 +1,65 @@
+<body role="document">
+<%= render '_sidebar_toggle.rhtml' %>
+
+<nav id="navigation" role="navigation" hidden>
+  <div id="project-navigation">
+    <div id="home-section" class="nav-section">
+      <h2>
+        <a href="<%= rel_prefix %>/" rel="home">Home</a>
+      </h2>
+    </div>
+
+    <%= render '_sidebar_search.rhtml' %>
+  </div>
+
+  <%= render '_sidebar_installed.rhtml' %>
+</nav>
+
+<main role="main">
+  <h1>Local RDoc Documentation</h1>
+
+  <p>Here you can browse local documentation from the ruby standard library and
+  your installed gems.</p>
+
+<%- extra_dirs = installed.select { |_, _, _, type,| type == :extra } %>
+<%- unless extra_dirs.empty? %>
+  <h2>Extra Documentation Directories</h2>
+
+  <p>The following additional documentation directories are available:</p>
+
+  <ol>
+  <%- extra_dirs.each do |name, href, exists, _, path| %>
+    <li>
+    <%- if exists %>
+      <a href="<%= href %>"><%= h name %></a> (<%= h path %>)
+    <%- else %>
+      <%= h name %> (<%= h path %>; <i>not available</i>)
+    <%- end %>
+    </li>
+  <%- end %>
+  </ol>
+<%- end %>
+
+<%- gems = installed.select { |_, _, _, type,| type == :gem } %>
+<%- missing = gems.reject { |_, _, exists,| exists } %>
+<%- unless missing.empty? then %>
+  <h2>Missing Gem Documentation</h2>
+
+  <p>You are missing documentation for some of your installed gems.
+  You can install missing documentation for gems by running
+  <kbd>gem rdoc --all</kbd>.  After installing the missing documentation you
+  only need to reload this page.  The newly created documentation will
+  automatically appear.</p>
+
+  <p>You can also install documentation for a specific gem by running one of
+  the following commands.</p>
+
+  <ul>
+  <%- names = missing.map { |name,| name.sub(/-([^-]*)$/, '') }.uniq %>
+  <%- names.each do |name| %>
+    <li><kbd>gem rdoc <%= h name %></kbd></li>
+  <%- end %>
+  </ul>
+<%- end %>
+</main>
+</body>

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

@@ -16,13 +16,8 @@
   <meta name="description" content="<%= h "#{file.page_name}: #{excerpt(file.comment)}" %>">
 <%- elsif @title %>
   <meta name="keywords" content="ruby,documentation,<%= h @title %>">
-
-  <%- if @options.main_page and
-      main_page = @files.find { |f| f.full_name == @options.main_page } then %>
-    <meta name="description" content="<%= h "#{@title}: #{excerpt(main_page.comment)}" %>">
-  <%- else %>
-    <meta name="description" content="Documentation for <%= h @title %>">
-  <%- end %>
+<% description = @main_page ? "#{@title}: #{excerpt(@main_page.comment)}" : "Documentation for #{@title}" %>
+  <meta name="description" content="<%= h description %>">
 <%- end %>
 
 <%- if canonical_url = @options.canonical_root %>

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

@@ -13,7 +13,7 @@
     <%- f = files.shift %>
     <%- if files.empty? %>
     <li><a href="<%= rel_prefix %>/<%= h f.path %>"><%= h f.page_name %></a></li>
-      <%- next %>
+      <%- next -%>
     <%- end %>
     <li><details<%= ' open' if dir == n %>><summary><%
     if n == f.page_name

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

@@ -4,6 +4,7 @@
       <input id="search-field" role="combobox" aria-label="Search"
              aria-autocomplete="list" aria-controls="search-results"
              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>
 

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

@@ -117,10 +117,10 @@
     </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><%= visibility.to_s.capitalize %> <%= type.capitalize %> Methods</h3>
@@ -163,15 +163,13 @@
               <summary>Source</summary>
             </details>
           </div>
+          <div class="method-source-code" id="<%= method.html_name %>-source">
+            <pre><%= 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><%= 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>
@@ -215,8 +213,8 @@
 
     <%- end %>
     </section>
-  <%- end
-     end %>
+  <%- end %>
+  <%- end %>
   </section>
 <%- end %>
 </main>

data/lib/rdoc/generator/template/darkfish/table_of_contents.rhtml

@@ -47,7 +47,7 @@
    unless table.empty? then %>
     <ul>
 <%- table.each do |item| %>
-<%-   label = item.respond_to?(:label) ? item.label(klass) : item.aref %>
+  <%- label = item.respond_to?(:label) ? item.label(klass) : item.aref %>
       <li><a href="<%= klass.path %>#<%= label %>"><%= item.plain_html %></a></li>
 <%- end %>
     </ul>

data/lib/rdoc/generator/template/json_index/js/searcher.js

@@ -57,10 +57,14 @@ Searcher.prototype = new function() {
   }
 
   function buildRegexps(queries) {
+    // A small minority of older browsers don't have RegExp.escape
+    // but it's not worth including a complex polyfill.
+    var escape = RegExp.escape || function(s) { return s };
+
     return queries.map(function(query) {
       var pattern = [];
       for (var i = 0; i < query.length; i++) {
-        var char = RegExp.escape(query[i]);
+        var char = escape(query[i]);
         pattern.push('([' + char + '])([^' + char + ']*?)');
       }
       return new RegExp(pattern.join(''), 'i');

data/lib/rdoc/generator.rb

@@ -43,6 +43,7 @@ module RDoc::Generator
 
   autoload :Markup,   "#{__dir__}/generator/markup"
 
+  autoload :Aliki,     "#{__dir__}/generator/aliki"
   autoload :Darkfish,  "#{__dir__}/generator/darkfish"
   autoload :JsonIndex, "#{__dir__}/generator/json_index"
   autoload :RI,        "#{__dir__}/generator/ri"

data/lib/rdoc/markup/blank_line.rb

@@ -1,27 +1,29 @@
 # frozen_string_literal: true
-##
-# An empty line.  This class is a singleton.
 
-class RDoc::Markup::BlankLine
-
-  @instance = new
-
-  ##
-  # RDoc::Markup::BlankLine is a singleton
-
-  def self.new
-    @instance
+module RDoc
+  class Markup
+    # An empty line
+    class BlankLine < Element
+      @instance = new
+
+      # RDoc::Markup::BlankLine is a singleton
+      #: () -> BlankLine
+      def self.new
+        @instance
+      end
+
+      # Calls #accept_blank_line on +visitor+
+      # @override
+      #: (untyped) -> void
+      def accept(visitor)
+        visitor.accept_blank_line(self)
+      end
+
+      # @override
+      #: (PP) -> void
+      def pretty_print(q) # :nodoc:
+        q.text("blankline")
+      end
+    end
   end
-
-  ##
-  # Calls #accept_blank_line on +visitor+
-
-  def accept(visitor)
-    visitor.accept_blank_line self
-  end
-
-  def pretty_print(q) # :nodoc:
-    q.text 'blankline'
-  end
-
 end

data/lib/rdoc/markup/element.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module RDoc
+  class Markup
+    # Base class defining the interface for all markup elements found in documentation
+    # @abstract
+    class Element
+      # @abstract
+      #: (untyped) -> void
+      def accept(visitor)
+        raise NotImplementedError, "#{self.class} must implement the accept method"
+      end
+
+      # @abstract
+      #: (PP) -> void
+      def pretty_print(q)
+        raise NotImplementedError, "#{self.class} must implement the pretty_print method"
+      end
+    end
+  end
+end