rdoc 6.15.0 → 7.0.1

data/lib/rdoc/generator/aliki.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+##
+# Aliki theme for RDoc documentation
+#
+# Author: Stan Lo
+#
+
+class RDoc::Generator::Aliki < RDoc::Generator::Darkfish
+  RDoc::RDoc.add_generator self
+
+  def initialize(store, options)
+    super
+    aliki_template_dir = File.expand_path(File.join(__dir__, 'template', 'aliki'))
+    @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
+  # generated documentation lightweight.
+
+  def write_style_sheet
+    debug_msg "Copying Aliki static files"
+    options = { verbose: $DEBUG_RDOC, noop: @dry_run }
+
+    install_rdoc_static_file @template_dir + 'css/rdoc.css', "./css/rdoc.css", options
+
+    unless @options.template_stylesheets.empty?
+      FileUtils.cp @options.template_stylesheets, '.', **options
+    end
+
+    Dir[(@template_dir + 'js/**/*').to_s].each do |path|
+      next if File.directory?(path)
+      next if File.basename(path).start_with?('.')
+
+      dst = Pathname.new(path).relative_path_from(@template_dir)
+
+      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

@@ -314,6 +314,8 @@ class RDoc::Generator::Darkfish
   # Generates a class file for +klass+
 
   def generate_class(klass, template_file = nil)
+    # This is used to auto-collapse Pages section on class/module pages
+    @inside_class_file = true
     current = klass
 
     template_file ||= @template_dir + 'class.rhtml'
@@ -338,6 +340,8 @@ class RDoc::Generator::Darkfish
       here.local_variable_set(:asset_rel_prefix, asset_rel_prefix)
       here
     end
+  ensure
+    @inside_class_file = false
   end
 
   ##
@@ -764,7 +768,7 @@ class RDoc::Generator::Darkfish
   end
 
   def traverse_classes(klasses, grouped_classes, rel_prefix, solo = false)
-    content = +'<ul class="link-list">'
+    content = +'<ul class="link-list nav-list">'
 
     klasses.each do |index_klass|
       if children = grouped_classes[index_klass.full_name]

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

@@ -0,0 +1,8 @@
+<aside class="table-of-contents" role="complementary" aria-label="Table of Contents">
+  <div class="toc-sticky">
+    <h3 class="toc-heading">On This Page</h3>
+    <nav class="toc-nav" id="toc-nav" aria-label="Page sections">
+      <!-- Generated by JavaScript based on page headings -->
+    </nav>
+  </div>
+</aside>

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

@@ -0,0 +1,23 @@
+<footer class="site-footer">
+  <% if @options.footer_content && !@options.footer_content.empty? %>
+  <div class="footer-content">
+    <% @options.footer_content.each do |column_title, links| %>
+    <div>
+      <h3><%= h column_title %></h3>
+      <ul>
+        <% links.each do |text, url| %>
+        <li><a href="<%= h resolve_url(rel_prefix, url) %>"><%= h text %></a></li>
+        <% end %>
+      </ul>
+    </div>
+    <% end %>
+  </div>
+  <% end %>
+
+  <div class="footer-bottom">
+    <p>
+      Generated by <a href="https://ruby.github.io/rdoc/">RDoc <%= RDoc::VERSION %></a>
+      using the Aliki theme by <a href="http://st0012.dev">Stan Lo</a>
+    </p>
+  </div>
+</footer>

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

@@ -0,0 +1,158 @@
+<meta charset="<%= @options.charset %>">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+
+<title><%= h @title %></title>
+
+<%- if defined?(klass) %>
+  <meta
+    name="keywords"
+    content="ruby,<%= h "#{klass.type},#{klass.full_name}" %>"
+  >
+  <%- if klass.comment.empty? %>
+    <meta
+      name="description"
+      content="Documentation for the <%= h "#{klass.full_name} #{klass.type}" %>"
+    >
+  <%- else %>
+    <meta
+      name="description"
+      content="<%= h "#{klass.type} #{klass.full_name}: #{excerpt(klass.comment)}" %>"
+    >
+  <%- end %>
+<%- elsif defined?(file) %>
+  <meta name="keywords" content="ruby,documentation,<%= h file.page_name %>">
+  <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 %>
+<%- end %>
+
+<%- if canonical_url = @options.canonical_root %>
+  <% canonical_url = current.canonical_url if defined?(current) %>
+  <link rel="canonical" href="<%= canonical_url %>">
+<%- end %>
+
+<!-- Open Graph / Facebook -->
+<meta property="og:type" content="website">
+<meta property="og:title" content="<%= h @title %>">
+
+<%- if defined?(klass) %>
+  <%- if klass.comment.empty? %>
+    <meta
+      property="og:description"
+      content="Documentation for <%= h klass.full_name %> <%= h klass.type %> - API reference and code examples"
+    >
+  <%- else %>
+    <meta property="og:description" content="<%= h excerpt(klass.comment) %>">
+  <%- end %>
+<%- elsif defined?(file) %>
+  <%- if file.comment.empty? %>
+    <meta
+      property="og:description"
+      content="<%= h file.page_name %> - <%= h @title %> documentation"
+    >
+  <%- else %>
+    <meta property="og:description" content="<%= h excerpt(file.comment) %>">
+  <%- end %>
+<%- else %>
+  <meta
+    property="og:description"
+    content="API documentation for <%= h @title %> - Browse classes, modules, and methods"
+  >
+<%- end %>
+
+<%- if canonical_url = @options.canonical_root %>
+  <% canonical_url = current.canonical_url if defined?(current) %>
+  <meta property="og:url" content="<%= canonical_url %>">
+<%- end %>
+
+<!-- Twitter -->
+<meta name="twitter:card" content="summary">
+<meta name="twitter:title" content="<%= h @title %>">
+
+<%- if defined?(klass) %>
+  <%- if klass.comment.empty? %>
+    <meta
+      name="twitter:description"
+      content="Documentation for <%= h klass.full_name %> <%= h klass.type %> - API reference and code examples"
+    >
+  <%- else %>
+    <meta name="twitter:description" content="<%= h excerpt(klass.comment) %>">
+  <%- end %>
+<%- elsif defined?(file) %>
+  <%- if file.comment.empty? %>
+    <meta
+      name="twitter:description"
+      content="<%= h file.page_name %> - <%= h @title %> documentation"
+    >
+  <%- else %>
+    <meta name="twitter:description" content="<%= h excerpt(file.comment) %>">
+  <%- end %>
+<%- else %>
+  <meta
+    name="twitter:description"
+    content="API documentation for <%= h @title %> - Browse classes, modules, and methods"
+  >
+<%- end %>
+
+<script type="text/javascript">
+  var rdoc_rel_prefix = "<%= h asset_rel_prefix %>/";
+  var index_rel_prefix = "<%= h rel_prefix %>/";
+</script>
+
+<script
+  src="<%= h asset_rel_prefix %>/js/theme-toggle.js?v=<%= h RDoc::VERSION %>"
+></script>
+
+<script
+  src="<%= h asset_rel_prefix %>/js/search_navigation.js?v=<%= h RDoc::VERSION %>"
+  defer
+></script>
+
+<script
+  src="<%= h asset_rel_prefix %>/js/search_data.js?v=<%= h RDoc::VERSION %>"
+  defer
+></script>
+
+<script
+  src="<%= h asset_rel_prefix %>/js/search_ranker.js?v=<%= h RDoc::VERSION %>"
+  defer
+></script>
+
+<script
+  src="<%= h asset_rel_prefix %>/js/search_controller.js?v=<%= h RDoc::VERSION %>"
+  defer
+></script>
+
+<script
+  src="<%= h asset_rel_prefix %>/js/c_highlighter.js?v=<%= h RDoc::VERSION %>"
+  defer
+></script>
+
+<script
+  src="<%= h asset_rel_prefix %>/js/aliki.js?v=<%= h RDoc::VERSION %>"
+  defer
+></script>
+
+<link
+  href="<%= h asset_rel_prefix %>/css/rdoc.css?v=<%= h RDoc::VERSION %>"
+  rel="stylesheet"
+>
+
+<%- @options.template_stylesheets.each do |stylesheet| %>
+  <link
+    href="<%= h asset_rel_prefix %>/<%= h File.basename stylesheet %>?v=<%= h RDoc::VERSION %>"
+    rel="stylesheet"
+  >
+<%- end %>

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

@@ -0,0 +1,56 @@
+<header class="top-navbar">
+  <a href="<%= rel_prefix %>/index.html" class="navbar-brand">
+    <%= h @options.title %>
+  </a>
+
+  <!-- Desktop search bar -->
+  <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-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-desktop" aria-label="Search Results"
+          aria-busy="false" aria-expanded="false"
+          aria-atomic="false" class="initially-hidden search-results"></ul>
+    </form>
+  </div>
+
+  <!-- Mobile search icon button -->
+  <button id="search-toggle" class="navbar-search-mobile" aria-label="Open search" type="button">
+    <span aria-hidden="true">🔍</span>
+  </button>
+
+  <!-- Theme toggle button -->
+  <button id="theme-toggle" class="theme-toggle" aria-label="Switch to dark mode" type="button">
+    <span class="theme-toggle-icon" aria-hidden="true">🌙</span>
+  </button>
+</header>
+
+<!-- Search Modal (Mobile) -->
+<div id="search-modal" class="search-modal" hidden aria-modal="true" role="dialog" aria-label="Search">
+  <div class="search-modal-backdrop"></div>
+  <div class="search-modal-content">
+    <div class="search-modal-header">
+      <form class="search-modal-form" action="#" method="get" accept-charset="utf-8">
+        <span class="search-modal-icon" aria-hidden="true">🔍</span>
+        <input id="search-field-mobile" role="combobox" aria-label="Search"
+               aria-autocomplete="list" aria-controls="search-results-mobile"
+               type="text" name="search" placeholder="Search documentation"
+               spellcheck="false" autocomplete="off">
+        <button type="button" class="search-modal-close" aria-label="Close search" id="search-modal-close">
+          <span aria-hidden="true">esc</span>
+        </button>
+      </form>
+    </div>
+    <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-results search-modal-results initially-hidden"></ul>
+      <div class="search-modal-empty">
+        <p>No recent searches</p>
+      </div>
+    </div>
+  </div>
+</div>

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

@@ -0,0 +1,208 @@
+<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+  <!-- Chevron (right arrow) - used for expand/collapse -->
+  <symbol
+    id="icon-chevron"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="2"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  >
+    <polyline points="9 18 15 12 9 6"></polyline>
+  </symbol>
+
+  <!-- File/Document - Pages section -->
+  <symbol
+    id="icon-file"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="2"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  >
+    <path
+      d="M14.5 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7.5L14.5 2z"
+    ></path>
+
+    <polyline points="14 2 14 8 20 8"></polyline>
+  </symbol>
+
+  <!-- Layers/Stack - Classes and Modules section -->
+  <symbol
+    id="icon-layers"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="2"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  >
+    <polygon points="12 2 2 7 12 12 22 7 12 2"></polygon>
+    <polyline points="2 17 12 22 22 17"></polyline>
+    <polyline points="2 12 12 17 22 12"></polyline>
+  </symbol>
+
+  <!-- Curly braces with C - Class Methods section -->
+  <symbol
+    id="icon-class-methods"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="2"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  >
+    <path d="M6 3C3.5 3 2 4.5 2 7v3c0 1.5-1 2-1 2s1 .5 1 2v5c0 2.5 1.5 4 4 4"></path>
+    <path d="M18 3c2.5 0 4 1.5 4 4v3c0 1.5 1 2 1 2s-1 .5-1 2v5c0 2.5-1.5 4-4 4"></path>
+
+    <text
+      x="12"
+      y="17"
+      text-anchor="middle"
+      font-size="13"
+      font-weight="bold"
+      fill="currentColor"
+      stroke="none"
+    >
+      C
+    </text>
+  </symbol>
+
+  <!-- Curly braces with I - Instance Methods section -->
+  <symbol
+    id="icon-instance-methods"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="2"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  >
+    <path d="M6 3C3.5 3 2 4.5 2 7v3c0 1.5-1 2-1 2s1 .5 1 2v5c0 2.5 1.5 4 4 4"></path>
+    <path d="M18 3c2.5 0 4 1.5 4 4v3c0 1.5 1 2 1 2s-1 .5-1 2v5c0 2.5-1.5 4-4 4"></path>
+
+    <text
+      x="12"
+      y="17"
+      text-anchor="middle"
+      font-size="13"
+      font-weight="bold"
+      fill="currentColor"
+      stroke="none"
+    >
+      I
+    </text>
+  </symbol>
+
+  <!-- Double chevrons up - Ancestors section -->
+  <symbol
+    id="icon-ancestors"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="2"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  >
+    <polyline points="17 11 12 6 7 11"></polyline>
+    <polyline points="17 18 12 13 7 18"></polyline>
+  </symbol>
+
+  <!-- User with plus - Included Modules section -->
+  <symbol
+    id="icon-includes"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="2"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  >
+    <path d="M16 21v-2a4 4 0 0 0-4-4H5a4 4 0 0 0-4 4v2"></path>
+    <circle cx="8.5" cy="7" r="4"></circle>
+
+    <line
+      x1="20"
+      y1="8"
+      x2="20"
+      y2="14"
+    ></line>
+
+    <line
+      x1="23"
+      y1="11"
+      x2="17"
+      y2="11"
+    ></line>
+  </symbol>
+
+  <!-- User with check - Extended Modules section -->
+  <symbol
+    id="icon-extends"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="2"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  >
+    <path d="M16 21v-2a4 4 0 0 0-4-4H5a4 4 0 0 0-4 4v2"></path>
+    <circle cx="8.5" cy="7" r="4"></circle>
+    <polyline points="17 11 19 13 23 9"></polyline>
+  </symbol>
+
+  <!-- List - Sections section -->
+  <symbol
+    id="icon-list"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="2"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  >
+    <line
+      x1="8"
+      y1="6"
+      x2="21"
+      y2="6"
+    ></line>
+
+    <line
+      x1="8"
+      y1="12"
+      x2="21"
+      y2="12"
+    ></line>
+
+    <line
+      x1="8"
+      y1="18"
+      x2="21"
+      y2="18"
+    ></line>
+
+    <line
+      x1="3"
+      y1="6"
+      x2="3.01"
+      y2="6"
+    ></line>
+
+    <line
+      x1="3"
+      y1="12"
+      x2="3.01"
+      y2="12"
+    ></line>
+
+    <line
+      x1="3"
+      y1="18"
+      x2="3.01"
+      y2="18"
+    ></line>
+  </symbol>
+</svg>

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

@@ -0,0 +1,16 @@
+<%- if klass.type == 'class' && (ancestors = klass.super_classes).any? %>
+<div id="parent-class-section" class="nav-section">
+  <details class="nav-section-collapsible" open>
+    <summary class="nav-section-header">
+      <span class="nav-section-icon">
+        <svg><use href="#icon-ancestors"></use></svg>
+      </span>
+      <span class="nav-section-title">Ancestors</span>
+      <span class="nav-section-chevron">
+        <svg><use href="#icon-chevron"></use></svg>
+      </span>
+    </summary>
+    <%= generate_ancestor_list(ancestors, klass) %>
+  </details>
+</div>
+<%- end %>

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

@@ -0,0 +1,15 @@
+<div id="classindex-section" class="nav-section">
+  <details class="nav-section-collapsible" open>
+    <summary class="nav-section-header">
+      <span class="nav-section-icon">
+        <svg><use href="#icon-layers"></use></svg>
+      </span>
+      <span class="nav-section-title">Classes and Modules</span>
+      <span class="nav-section-chevron">
+        <svg><use href="#icon-chevron"></use></svg>
+      </span>
+    </summary>
+
+    <%= generate_class_index_content(@classes, rel_prefix) %>
+  </details>
+</div>