From fee9e2c7ab44f79c3b7a066b1f66bd1092835468 Mon Sep 17 00:00:00 2001
From: Petrik <petrik@deheus.net>
Date: Sat, 31 May 2025 11:50:33 +0200
Subject: [PATCH] Add version selector

To make it easier to switch to documentation of other versions, add a
select box to select other versions.

For example, the versions can be defined in `.rdoc_options`:

```yaml
version_roots:
  latest: https://docs.ruby-lang.org/en/
  master: https://docs.ruby-lang.org/en/master/
  3.4: https://docs.ruby-lang.org/en/3.4/
```
---
 lib/rdoc/generator/markup.rb                  | 16 +++++++++
 .../darkfish/_sidebar_navigation.rhtml        |  8 +++++
 .../template/darkfish/js/darkfish.js          |  8 +++++
 lib/rdoc/options.rb                           |  7 ++++
 test/rdoc/rdoc_generator_darkfish_test.rb     | 33 +++++++++++++++++++
 test/rdoc/rdoc_options_test.rb                |  1 +
 6 files changed, 73 insertions(+)

diff --git a/lib/rdoc/generator/markup.rb b/lib/rdoc/generator/markup.rb
index 1c39687040..5bb97c6176 100644
--- a/lib/rdoc/generator/markup.rb
+++ b/lib/rdoc/generator/markup.rb
@@ -67,6 +67,22 @@ def canonical_url
     end
   end
 
+  ##
+  # URL's to other versions for this object.
+
+  def version_urls
+    options = @store.options
+    if options.version_roots
+      options.version_roots.map do |version, root|
+        if path
+          url = File.join(root, path.to_s)
+          [version, url]
+        else
+          [version, root]
+        end
+      end
+    end
+  end
 end
 
 class RDoc::CodeObject
diff --git a/lib/rdoc/generator/template/darkfish/_sidebar_navigation.rhtml b/lib/rdoc/generator/template/darkfish/_sidebar_navigation.rhtml
index d7f330840a..5964835bea 100644
--- a/lib/rdoc/generator/template/darkfish/_sidebar_navigation.rhtml
+++ b/lib/rdoc/generator/template/darkfish/_sidebar_navigation.rhtml
@@ -1,6 +1,14 @@
 <div id="home-section" role="region" title="Quick navigation" class="nav-section">
   <h2>
     <a href="<%= rel_prefix %>/index.html" rel="home">Home</a>
+    <% if version_urls = @options.version_roots %>
+    <% version_urls = current.version_urls if defined?(current) %>
+    <select id="version-select">
+      <% version_urls.each do |version, url| %>
+        <option value="<%= url %>"><%= version %></option>
+      <% end %>
+    </select>
+    <% end %>
   </h2>
 
   <div id="table-of-contents-navigation">
diff --git a/lib/rdoc/generator/template/darkfish/js/darkfish.js b/lib/rdoc/generator/template/darkfish/js/darkfish.js
index 4c15efde66..250ba609e2 100644
--- a/lib/rdoc/generator/template/darkfish/js/darkfish.js
+++ b/lib/rdoc/generator/template/darkfish/js/darkfish.js
@@ -33,6 +33,13 @@ function showSource( e ) {
   }
 };
 
+function hookVersionSelect() {
+  var versionSelect = document.querySelector('#version-select');
+  versionSelect.addEventListener('change', function (e) {
+    window.location.href = e.target.value;
+  });
+};
+
 function hookSourceViews() {
   document.querySelectorAll('.method-source-toggle').forEach(function (codeObject) {
     codeObject.addEventListener('click', showSource);
@@ -113,6 +120,7 @@ function hookSidebar() {
 }
 
 document.addEventListener('DOMContentLoaded', function() {
+  hookVersionSelect();
   hookSourceViews();
   hookSearch();
   hookFocus();
diff --git a/lib/rdoc/options.rb b/lib/rdoc/options.rb
index 9ab0385bfa..b00b9fa631 100644
--- a/lib/rdoc/options.rb
+++ b/lib/rdoc/options.rb
@@ -378,6 +378,11 @@ class RDoc::Options
 
   attr_accessor :canonical_root
 
+  ##
+  # The root URLs of other versions of the documentation
+
+  attr_accessor :version_roots
+
   def initialize(loaded_options = nil) # :nodoc:
     init_ivars
     override loaded_options if loaded_options
@@ -435,6 +440,7 @@ def init_ivars # :nodoc:
     @class_module_path_prefix = nil
     @file_path_prefix = nil
     @canonical_root = nil
+    @version_roots = nil
   end
 
   def init_with(map) # :nodoc:
@@ -499,6 +505,7 @@ def override(map) # :nodoc:
     @autolink_excluded_words = map['autolink_excluded_words'] if map.has_key?('autolink_excluded_words')
     @apply_default_exclude = map['apply_default_exclude'] if map.has_key?('apply_default_exclude')
     @canonical_root = map['canonical_root'] if map.has_key?('canonical_root')
+    @version_roots = map['version_roots'] if map.has_key?('version_roots')
 
     @warn_missing_rdoc_ref = map['warn_missing_rdoc_ref'] if map.has_key?('warn_missing_rdoc_ref')
 
diff --git a/test/rdoc/rdoc_generator_darkfish_test.rb b/test/rdoc/rdoc_generator_darkfish_test.rb
index 67715951ec..9500a8e30a 100644
--- a/test/rdoc/rdoc_generator_darkfish_test.rb
+++ b/test/rdoc/rdoc_generator_darkfish_test.rb
@@ -562,6 +562,39 @@ def test_canonical_url_for_rdoc_files
     assert_include(content, '<link rel="canonical" href="https://docs.ruby-lang.org/en/master/CONTRIBUTING_rdoc.html">')
   end
 
+  def test_version_select_for_index
+    @store.options.version_roots = @options.version_roots = {
+      "master" => "https://docs.ruby-lang.org/en/master/",
+      "3.4"    => "https://docs.ruby-lang.org/en/3.4/"
+    }
+    @g.generate
+
+    content = File.binread("index.html")
+
+    assert_include(content, '<select id="version-select">')
+    assert_include(content, '<option value="https://docs.ruby-lang.org/en/master/">master</option>')
+    assert_include(content, '<option value="https://docs.ruby-lang.org/en/3.4/">3.4</option>')
+  end
+
+  def test_version_select_for_classes
+    top_level = @store.add_file("file.rb")
+    top_level.add_class(@klass.class, @klass.name)
+    inner = @klass.add_class(RDoc::NormalClass, "Inner")
+
+    @store.options.version_roots = @options.version_roots = {
+      "master" => "https://docs.ruby-lang.org/en/master/",
+      "3.4"    => "https://docs.ruby-lang.org/en/3.4/"
+    }
+    @g.generate
+
+    content = File.binread("Klass/Inner.html")
+
+    assert_include(content, '<select id="version-select">')
+    assert_include(content, '<option value="https://docs.ruby-lang.org/en/master/Klass/Inner.html">master</option>')
+    assert_include(content, '<option value="https://docs.ruby-lang.org/en/3.4/Klass/Inner.html">3.4</option>')
+  end
+
+
   ##
   # Asserts that +filename+ has a link count greater than 1 if hard links to
   # @tmpdir are supported.
diff --git a/test/rdoc/rdoc_options_test.rb b/test/rdoc/rdoc_options_test.rb
index 097d0f5523..f6fc70062e 100644
--- a/test/rdoc/rdoc_options_test.rb
+++ b/test/rdoc/rdoc_options_test.rb
@@ -90,6 +90,7 @@ def test_to_yaml
       'class_module_path_prefix' => nil,
       'file_path_prefix' => nil,
       'canonical_root' => nil,
+      'version_roots' => nil,
     }
 
     assert_equal expected, coder