Add banner feature to qiskit theme (#530)

In this PR:

- [x] add optional purple gradient banner to all pages
- [x] add optional "Learn more" link to banner
- [x] update readme
- [x] works for mobile view
- [ ] snapshot tests for banner component

I'm struggling to figure out how to add new snapshots for this
component, any help appreciated!

<img width="1330" alt="Screenshot 2023-08-07 at 5 13 10 PM"
src="https://github.com/Qiskit/qiskit_sphinx_theme/assets/23662430/02fe6fd7-59b1-448d-bd4e-5939e67b5ab7">

<img width="1327" alt="Screenshot 2023-08-07 at 5 12 02 PM"
src="https://github.com/Qiskit/qiskit_sphinx_theme/assets/23662430/68c2aecc-1303-4a89-b90b-b4ba7539c76a">

<img width="211" alt="Screenshot 2023-08-07 at 5 19 30 PM"
src="https://github.com/Qiskit/qiskit_sphinx_theme/assets/23662430/b3b7cd8f-9987-4ae5-9007-e6a79142d130">

README.md

@@ -132,7 +132,45 @@ By enabling analytics we will be able to collect information on number of visits
 
 If you do not enable analytics, no data will be collected and the `Was this page helpful?` component will not show.
 
-## Customize or disable the logo
+## Add an announcement banner to all pages
+
+> :warning: **Note:** This feature is currently only available for the Qiskit theme, it is not yet available in the Ecosystem theme
+
+
+The `qiskit` theme includes the ability to add a custom announcement banner to every page. You can configure this in your `conf.py` by adding your
+custom announcement text to the `theme_announcement` variable in the `html_context` object, for example:
+
+```
+html_context = {
+    "theme_announcement": "🎉 Custom announcement text!",
+}
+```
+The above code will enable the following banner:
+
+<img width="1330" alt="Screenshot 2023-08-07 at 5 13 10 PM" src="https://github.com/qiskit-community/ecosystem/assets/23662430/cbb86903-17fd-4752-a955-5e8c5eda3383">
+
+You can also optionally add a "Learn more" url by additionally setting the `announcement_url` in the `html_context`, like so:
+
+```
+html_context = {
+    "theme_announcement": "🎉 Custom announcement text!",
+    "announcement_url": "https://example.com"
+}
+```
+The above code will render the following banner:
+
+<img width="1327" alt="Screenshot 2023-08-07 at 5 12 02 PM" src="https://github.com/qiskit-community/ecosystem/assets/23662430/79ccb19d-3392-4ea9-993e-b006dc7481dc">
+
+The default text for the link is "Learn more" but you can provide custom link text by setting the `announcement_url_text` in the `html_context`:
+```
+html_context = {
+    "theme_announcement": "🎉 Custom announcement text!",
+    "announcement_url": "https://example.com",
+    "announcement_url_text": "Check it out",
+}
+```
+
+## Customize or disable the Ecosystem theme logo
 
 The `qiskit-ecosystem` theme includes the Qiskit Ecosystem logo by default.
 
@@ -154,7 +192,7 @@ html_theme_options = {
 }
 ```
 
-## IBM Projects: how to use blue color scheme
+## IBM Projects: how to use blue color scheme for Ecosystem theme
 
 By default, the `qiskit-ecosystem` theme uses purple as an accent color. Most projects should continue to use this, but certain highly IBM-affiliated projects like Qiskit IBM Runtime can change the accent color to blue by setting up `conf.py` like this:
 

example_docs/docs/conf.py

@@ -91,6 +91,10 @@
     # This allows docs authors to have folders that can be
     # closed and opened in the left sidebar.
     "expandable_sidebar": True,
+    # Users of the theme can set the text and optional url for an announcement banner
+    "theme_announcement": "🎉 Custom announcement text!",
+    "announcement_url_text": "Check it out",
+    "announcement_url": "https://google.com",
 }
 
 docs_url_prefix = "ecosystem/example_docs"

src/qiskit_sphinx_theme/assets/styles/_announcement.scss

@@ -0,0 +1,47 @@
+/* This code is a Qiskit project.
+ *
+ * (C) Copyright IBM 2023.
+ *
+ * This code is licensed under the Apache License, Version 2.0. You may
+ * obtain a copy of this license in the LICENSE.txt file in the root directory
+ * of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * Any modifications or derivative works of this code must retain this
+ * copyright notice, and modified files need to carry a notice indicating
+ * that they have been altered from the originals.
+ */
+
+ body {
+    --qiskit-top-nav-bar-height: 3.5rem;
+  }
+
+// custom announcement banner with purple gradient
+ .custom-announcement {
+    background: linear-gradient(90deg, rgba(245,239,255,1) 0%, rgba(255,255,255,1) 100%);
+    border-bottom: 1px solid var(--color-background-border);
+    padding: 14px var(--sidebar-item-spacing-horizontal);
+    display: flex;
+    align-items: center;
+ }
+
+// custom styling for inner text/link content for custom announcement banner 
+ .custom-announcement-content {
+    text-align: left;
+    font-weight: bold;
+    color: black;
+
+    a {
+        color: var(--qiskit-color-purple);
+        font-weight: normal;
+        padding-left: 0.5rem;
+
+        &:hover {
+            color: var(--qiskit-color-purple);
+        }
+
+        .icon {
+            position: relative;
+            top: 0.15rem;
+        }
+    }
+ }

src/qiskit_sphinx_theme/assets/styles/qiskit-sphinx-theme.scss

@@ -12,6 +12,7 @@
  */
 
 @import "admonitions";
+@import "announcement";
 @import "api";
 @import "colors";
 @import "custom-directives";

src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/page.html

@@ -28,9 +28,19 @@
 </label>
 
 {% if theme_announcement -%}
-<div class="announcement">
-  <aside class="announcement-content">
+<div class="custom-announcement">
+  <aside class="custom-announcement-content">
     {% block announcement %} {{ theme_announcement }} {% endblock announcement %}
+    {% if announcement_url -%}
+    <a href="{{announcement_url}}" class="reference internal">
+      {% if announcement_url_text -%}
+      {{announcement_url_text}}
+      {% else %}
+      Learn more
+      {%- endif %}
+      <svg class="icon"><use href="#svg-new-tab"></use></svg>
+    </a>
+    {%- endif %}
   </aside>
 </div>
 {%- endif %}

src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/partials/icons.html

@@ -41,6 +41,20 @@
       <rect id="_x3C_Transparent_Rectangle_x3E_" fill="none" width="32" height="32"/>
     </svg>
   </symbol>
+  <symbol id="svg-new-tab" viewBox="0 0 32 32">
+    <svg id="icon" xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32">
+      <defs>
+        <style>
+          .cls-1 {
+            fill: none;
+          }
+        </style>
+      </defs>
+      <path fill="#6929C4" d="M26,28H6a2.0027,2.0027,0,0,1-2-2V6A2.0027,2.0027,0,0,1,6,4H16V6H6V26H26V16h2V26A2.0027,2.0027,0,0,1,26,28Z"/>
+      <polygon fill="#6929C4" points="20 2 20 4 26.586 4 18 12.586 19.414 14 28 5.414 28 12 30 12 30 2 20 2"/>
+      <rect id="_Transparent_Rectangle_" data-name="&lt;Transparent Rectangle&gt;" class="cls-1" width="32" height="32"/>
+    </svg>
+  </symbol>
   <symbol id="svg-sun" viewBox="0 0 24 24">
     <title>Light mode</title>
     <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"