Rollup merge of #117662 - GuillaumeGomez:links-in-headings, r=notriddle

[rustdoc] Allows links in headings

Reopening of https://github.com/rust-lang/rust/pull/94360.

# Explanations

Rustdoc currently doesn't follow the markdown spec on headings: we don't allow links in them. So instead of having headings linking to themselves, this PR generates an anchor on the left side like this:

![image](https://github.com/rust-lang/rust/assets/3050060/a118a7e9-5ef8-4d07-914f-46defc3245c3)

<details>
<summary>previous version</summary>

![image](https://github.com/rust-lang/rust/assets/3050060/c34fa844-9cd4-47dc-bb51-b37f5f66afee)

</details>

Having the anchor always displayed allows for mobile devices users to be able to have a link to the anchor. The different color used for the anchor itself is the same as links so people notice when looking at it that they can click on it.

You can test it [here](https://rustdoc.crud.net/imperio/links-in-headings/std/index.html).

cc `@camelid`
r? `@notriddle`

tests/rustdoc-gui/docblock-details.goml

@@ -6,7 +6,7 @@ reload:
 
 // We first check that the headers in the `.top-doc` doc block still have their
 // bottom border.
-assert-text: (".top-doc .docblock > h3", "Hello")
+assert-text: (".top-doc .docblock > h3", "§Hello")
 assert-css: (
     ".top-doc .docblock > h3",
     {"border-bottom": "1px solid #d2d2d2"},

tests/rustdoc-gui/headers-color.goml

@@ -1,4 +1,4 @@
-// This test check for headers text and background colors for the different themes.
+// This test check for headings text and background colors for the different themes.
 
 define-function: (
     "check-colors",
@@ -45,7 +45,7 @@ call-function: (
         "color": "#c5c5c5",
         "code_header_color": "#e6e1cf",
         "focus_background_color": "rgba(255, 236, 164, 0.06)",
-        "headings_color": "#39afd7",
+        "headings_color": "#c5c5c5",
     },
 )
 call-function: (
@@ -55,7 +55,7 @@ call-function: (
         "color": "#ddd",
         "code_header_color": "#ddd",
         "focus_background_color": "#494a3d",
-        "headings_color": "#d2991d",
+        "headings_color": "#ddd",
     },
 )
 call-function: (
@@ -65,6 +65,6 @@ call-function: (
         "color": "black",
         "code_header_color": "black",
         "focus_background_color": "#fdffd3",
-        "headings_color": "#3873ad",
+        "headings_color": "black",
     },
 )

tests/rustdoc-gui/headings-anchor.goml

@@ -0,0 +1,32 @@
+// Test to ensure that the headings anchor behave as expected.
+go-to: "file://" + |DOC_PATH| + "/test_docs/struct.HeavilyDocumentedStruct.html"
+show-text: true
+
+define-function: (
+    "check-heading-anchor",
+    (heading_id),
+    block {
+        // The anchor should not be displayed by default.
+        assert-css: ("#" + |heading_id| + " .doc-anchor", { "display": "none" })
+        // We ensure that hovering the heading makes the anchor visible.
+        move-cursor-to: "#" + |heading_id|
+        assert-css: ("#" + |heading_id| + ":hover .doc-anchor", { "display": "block" })
+        // We then ensure that moving from the heading to the anchor doesn't make the anchor
+        // disappear.
+        move-cursor-to: "#" + |heading_id| + " .doc-anchor"
+        assert-css: ("#" + |heading_id| + " .doc-anchor:hover", {
+            "display": "block",
+            // We also ensure that there is no underline decoration.
+            "text-decoration-line": "none",
+        })
+    }
+)
+
+move-cursor-to: "#top-doc-prose-title"
+// If the top documentation block first element is a heading, we should never display its anchor
+// to prevent it from overlapping with the `[-]` element.
+assert-css: ("#top-doc-prose-title:hover .doc-anchor", { "display": "none" })
+
+call-function: ("check-heading-anchor", ("top-doc-prose-sub-heading"))
+call-function: ("check-heading-anchor", ("top-doc-prose-sub-sub-heading"))
+call-function: ("check-heading-anchor", ("you-know-the-drill"))