Improve accessibility of qiskit-card being clickable (#432)

#415 accidentally
broke `qiskit-card` being clickable.

But the code wasn't accessible, to begin with. It's an antipattern to
make a `<div>` clickable. Instead, we should use the semantic web with
an `<a>` element.

Pytorch renders the same as before:

![Screenshot 2023-06-29 at 2 38 53
PM](https://github.com/Qiskit/qiskit_sphinx_theme/assets/14852634/c9d66f39-cfc8-4b18-bcad-3daebee9eee4)

src/qiskit_sphinx_theme/assets/styles/_custom-directives.scss

@@ -13,6 +13,10 @@
   background-color: var(--color-sidebar-background);
   cursor: pointer;
 
+  // Turn off default rules for `<a>`.
+  color: unset;
+  text-decoration: none;
+
   p {
     color: var(--color-sidebar-link-text);
   }
@@ -35,6 +39,9 @@
     background-color: unset;
     border-bottom: none;
 
+    // Turn off default rule for `<a>`.
+    color: unset;
+
     p {
       color: unset;
     }

src/qiskit_sphinx_theme/directives.py

@@ -38,7 +38,7 @@ class QiskitCardDirective(Directive):
         "card_description": directives.unchanged,
     }
 
-    def run(self) -> list[nodes.paragraph]:
+    def run(self) -> list[nodes.Element]:
         header = self.options.get("header")
         if header is None:
             raise ValueError(f"`header` not set in {self.NAME} directive")
@@ -48,21 +48,17 @@ def run(self) -> list[nodes.paragraph]:
         link = self.options.get("link", "")
         card_description = self.options.get("card_description", "")
 
-        card_rst = f"""
-.. raw:: html
-
-    <div class="qiskit-card" link={link}>
+        html = f"""
+    <a class="qiskit-card" href="{link}">
       <div class="qiskit-card-text-container">
         <h3>{header}</h3>
         <p>{card_description}</p>
       </div>
       <div class="qiskit-card-image-container"><img src='{image_source}'></div>
-    </div>
+    </a>
 """
-        card_list = StringList(card_rst.splitlines())
-        card = nodes.paragraph()
-        self.state.nested_parse(card_list, self.content_offset, card)
-        return [card]
+        node = nodes.raw("", html, format="html")
+        return [node]
 
 
 class QiskitCallToActionItemDirective(Directive):

src/qiskit_sphinx_theme/pytorch/static/css/theme.css

@@ -11531,7 +11531,7 @@ a:hover {
 * qiskit-card
 * ------------------------------------------------------------------------------- */
 
-div.qiskit-card {
+a.qiskit-card {
   position: relative;
   display: flex;
   flex: 1 1 auto;
@@ -11548,13 +11548,13 @@ div.qiskit-card {
   cursor: pointer;
 }
 @media screen and (min-width: 1240px) {
-  div.qiskit-card {
+  a.qiskit-card {
     height: 200px;
     overflow: inherit;
   }
 }
 @media (min-width: 768px) and (max-width: 1239px) {
-  div.qiskit-card {
+  a.qiskit-card {
     height: 200px;
     overflow: scroll;
   }
@@ -11596,7 +11596,7 @@ div.qiskit-card {
   opacity: .075;
 }
 
-div.qiskit-card h3 {
+a.qiskit-card h3 {
   width: 70%;
   display: inline-flex;
   margin-bottom: 1.125rem;
@@ -11605,17 +11605,17 @@ div.qiskit-card h3 {
   color: #262626;
 }
 @media screen and (min-width: 768px) {
-  div.qiskit-card h3 {
+  a.qiskit-card h3 {
     width: 75%;
   }
 }
 @media (min-width: 768px) and (max-width: 1239px) {
-  div.qiskit-card h3 {
+  a.qiskit-card h3 {
     width: 70%;
   }
 }
 
-div.qiskit-card p {
+a.qiskit-card p {
   font-size: 0.9375rem;
   line-height: 1.5rem;
   margin-bottom: 0;
@@ -11624,18 +11624,18 @@ div.qiskit-card p {
   width: 70%;
 }
 @media screen and (min-width: 768px) {
-  div.qiskit-card p {
+  a.qiskit-card p {
     width: 75%;
   }
 }
 @media (min-width: 768px) and (max-width: 1239px) {
-  div.qiskit-card p {
+  a.qiskit-card p {
     width: 70%;
   }
 }
 
 @media screen and (min-width: 768px) {
-  div.qiskit-card:after {
+  a.qiskit-card:after {
     content: "";
     display: block;
     width: 0;
@@ -11647,20 +11647,20 @@ div.qiskit-card p {
     -webkit-transition: width .250s ease-in-out;
     transition: width .250s ease-in-out;
   }
-  div.qiskit-card:hover:after {
+  a.qiskit-card:hover:after {
     width: 100%;
   }
 }
 
-div.qiskit-card:hover {
+a.qiskit-card:hover {
   background-color: #ffffff;
   border: 1px solid #e2e2e2;
   border-bottom: none;
 }
-div.qiskit-card:hover p {
+a.qiskit-card:hover p {
   color: #262626;
 }
-div.qiskit-card:hover .qiskit-card-image-container {
+a.qiskit-card:hover .qiskit-card-image-container {
   opacity: unset;
 }
 

src/qiskit_sphinx_theme/pytorch/static/js/theme.js

@@ -895,12 +895,6 @@ if ($("p.caption:first").text() == "Notes") {
     }
 }
 
-// Get the card link from the card's link attribute
-
-$(".tutorials-card").on("click", function() {
-    window.location = $(this).attr("link");
-});
-
 // Build an array from each tag that's present
 
 var tagList = $(".tutorials-card-container").map(function() {