From 5617fb7dc933a0aa77fe62b2a15420d1b46d7e50 Mon Sep 17 00:00:00 2001
From: Jonathan Hefner <jonathan@hefner.pro>
Date: Tue, 2 Jan 2024 11:55:51 -0600
Subject: [PATCH] Support permalinking constants

This adds a permalink next to each constant's name, similar to methods.
This also adds a "Constants" navigation section in the sidebar, similar
to the "Methods" navigation section.

The permalinks are implemented by monkeypatching `RDoc::Constant` to
provide an `aref` method, just as `RDoc::ClassModule` and
`RDoc::MethodAttr` already do.
---
 CHANGELOG.md                                  |  1 +
 .../generator/template/rails/_context.rhtml   | 10 ++-
 .../template/rails/_module_nav.rhtml          |  9 +++
 .../template/rails/resources/css/main.css     | 73 +++++++++++--------
 lib/sdoc/rdoc_monkey_patches.rb               | 15 ++++
 spec/rdoc_monkey_patches_spec.rb              | 22 ++++++
 6 files changed, 96 insertions(+), 34 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a6a457f1..242f3538 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -37,6 +37,7 @@ Main (3.0.0.alpha)
 * [#323](https://github.com/rails/sdoc/pull/323) Update favicon [@jonathanhefner](https://github.com/jonathanhefner)
 * [#345](https://github.com/rails/sdoc/pull/345) Version explicit links to `api.rubyonrails.org` [@jonathanhefner](https://github.com/jonathanhefner)
 * [#356](https://github.com/rails/sdoc/pull/356) Redesign "Constants" section [@jonathanhefner](https://github.com/jonathanhefner)
+* [#357](https://github.com/rails/sdoc/pull/357) Support permalinking constants [@jonathanhefner](https://github.com/jonathanhefner)
 
 2.6.1
 =====
diff --git a/lib/rdoc/generator/template/rails/_context.rhtml b/lib/rdoc/generator/template/rails/_context.rhtml
index b0412dd2..cc0dc73c 100644
--- a/lib/rdoc/generator/template/rails/_context.rhtml
+++ b/lib/rdoc/generator/template/rails/_context.rhtml
@@ -58,9 +58,11 @@
     <% unless constants.empty? %>
       <h2 class="content__divider">Constants</h2>
       <% constants.each do |constant| %>
-        <div class="constant">
-          <div class="constant__name">
+        <div class="constant" id="<%= constant.aref %>">
+          <div class="constant__name permalink-container">
             <h3><%= short_name_for constant %></h3>
+            <%= link_to %(<img src="/i/link.svg" alt="Permalink">), constant,
+                  class: "permalink", title: "Permalink" %>
           </div>
           <%= description_for constant %>
           <div class="constant__source">
@@ -97,10 +99,10 @@
       <h2 class="content__divider"><%= visibility.to_s.capitalize %> <%= type %> methods</h2>
       <% methods.each do |method| %>
         <div class="method" id="<%= method.aref %>">
-          <div class="method__signature">
+          <div class="method__signature permalink-container">
             <h3><%= method_signature method %></h3>
             <%= link_to %(<img src="/i/link.svg" alt="Permalink">), method,
-                  class: "method__permalink", title: "Permalink" %>
+                  class: "permalink", title: "Permalink" %>
           </div>
 
           <% unless method.aliases.empty? %>
diff --git a/lib/rdoc/generator/template/rails/_module_nav.rhtml b/lib/rdoc/generator/template/rails/_module_nav.rhtml
index df6b063d..dc4aee9d 100644
--- a/lib/rdoc/generator/template/rails/_module_nav.rhtml
+++ b/lib/rdoc/generator/template/rails/_module_nav.rhtml
@@ -10,6 +10,15 @@
   </div>
 <% end %>
 
+<% unless (constants = @context.constants).empty? %>
+  <div class="nav__heading">Constants</div>
+  <ul class="nav__list">
+    <% constants.sort.each do |rdoc_constant| %>
+      <li><%= link_to short_name_for(rdoc_constant), rdoc_constant %></li>
+    <% end %>
+  </ul>
+<% end %>
+
 <% unless (methods = module_methods(@context)).empty? %>
   <div class="nav__heading">Methods</div>
   <ul class="nav__list">
diff --git a/lib/rdoc/generator/template/rails/resources/css/main.css b/lib/rdoc/generator/template/rails/resources/css/main.css
index c463eb7a..2ec512c9 100644
--- a/lib/rdoc/generator/template/rails/resources/css/main.css
+++ b/lib/rdoc/generator/template/rails/resources/css/main.css
@@ -758,6 +758,14 @@ html {
 .constant__name {
   padding-bottom: var(--space-xs);
   border-bottom: 2px solid var(--code-bg);
+
+  display: flex;
+  align-items: baseline;
+  gap: 0.5em;
+}
+
+.constant__name > * {
+  margin-top: 0;
 }
 
 .constant__name code {
@@ -785,10 +793,11 @@ html {
 
   display: flex;
   align-items: baseline;
+  gap: 0.5em;
 }
 
-.method__signature h3 {
-  position: relative;
+.method__signature > * {
+  margin-top: 0;
 }
 
 .method__signature code {
@@ -801,34 +810,6 @@ html {
   font-size: 1.1em;
 }
 
-.target .method__signature code::before {
-  content: " ";
-
-  position: absolute;
-  left: calc(-0.5ch - var(--space-sm));
-  border-left: 0.5ch solid var(--link-color);
-  border-radius: 0.5ch;
-  height: 100%;
-}
-
-.method__permalink {
-  margin: 0 0 0 0.5em;
-}
-
-.method__permalink img {
-  font-family: monospace; /* Make em equivalent to <code>'s em */
-  height: 1em;
-  vertical-align: middle;
-}
-
-@media (hover: hover) {
-  .method__permalink:hover img {
-    filter: brightness(0) invert(1);
-    mix-blend-mode: difference;
-  }
-}
-
-
 .method__signature + * {
   margin-top: var(--space-sm);
 }
@@ -874,6 +855,38 @@ html {
 }
 
 
+/*
+ * Permalink
+ */
+
+.permalink img {
+  height: 1.05em;
+  vertical-align: middle;
+}
+
+@media (hover: hover) {
+  .permalink:hover img {
+    filter: brightness(0) invert(1);
+    mix-blend-mode: difference;
+  }
+}
+
+.permalink-container {
+  position: relative;
+}
+
+:is(.target .permalink-container, .target.permalink-container)::before {
+  content: " ";
+  white-space: pre;
+
+  position: absolute;
+  left: calc(-0.5ch - var(--space-sm));
+  border-left: 0.5ch solid var(--link-color);
+  border-radius: 0.5ch;
+  height: 100%;
+}
+
+
 /*
  * More-Less widget
  */
diff --git a/lib/sdoc/rdoc_monkey_patches.rb b/lib/sdoc/rdoc_monkey_patches.rb
index e2269615..ce858e5e 100644
--- a/lib/sdoc/rdoc_monkey_patches.rb
+++ b/lib/sdoc/rdoc_monkey_patches.rb
@@ -9,6 +9,21 @@ def path
 end)
 
 
+RDoc::Constant.prepend(Module.new do
+  def aref_prefix
+    "constant"
+  end
+
+  def aref
+    "#{aref_prefix}-#{name}"
+  end
+
+  def path
+    "#{super.sub(/#.+/, "")}##{aref}"
+  end
+end)
+
+
 RDoc::AnyMethod.prepend(Module.new do
   def params
     super&.sub(/\A\(\s+/, "(")&.sub(/\s+\)\z/, ")")
diff --git a/spec/rdoc_monkey_patches_spec.rb b/spec/rdoc_monkey_patches_spec.rb
index 6eed23db..bd980c52 100644
--- a/spec/rdoc_monkey_patches_spec.rb
+++ b/spec/rdoc_monkey_patches_spec.rb
@@ -12,6 +12,28 @@
     end
   end
 
+  describe RDoc::Constant do
+    it "implements #aref" do
+      rdoc_constant = rdoc_top_level_for(<<~RUBY).find_module_named("Foo").find_constant_named("BAR_QUX")
+        module Foo
+          BAR_QUX = true
+        end
+      RUBY
+
+      _(rdoc_constant.aref).must_equal "constant-BAR_QUX"
+    end
+
+    it "uses #aref in #path" do
+      rdoc_constant = rdoc_top_level_for(<<~RUBY).find_module_named("Foo").find_constant_named("BAR_QUX")
+        module Foo
+          BAR_QUX = true
+        end
+      RUBY
+
+      _(rdoc_constant.path).must_equal "classes/Foo.html#constant-BAR_QUX"
+    end
+  end
+
   describe RDoc::AnyMethod do
     it "omits extra whitespace in #params" do
       rdoc_method = rdoc_top_level_for(<<~RUBY).find_module_named("Foo").find_method("bar", false)