Customize Furo to use Qiskit branding

Qiskit · Apr 10, 2023 · f82c97d · f82c97d
1 parent 791497d
commit f82c97d
Show file tree

Hide file tree

Showing 7 changed files with 390 additions and 37 deletions.
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -0,0 +1,35 @@
+/* ------------------------------
+* User analytics in the footer
+* ------------------------------ */
+
+/* TODO: why won't the border render?? */
+footer .helpful-hr {
+  border-top: 1px solid rgba(0, 0, 0, 0.1);
+}
+
+footer .helpful-container {
+  display: -webkit-inline-box;
+  display: -ms-inline-flexbox;
+  display: inline-flex;
+}
+
+footer .helpful-container .helpful-question,
+footer .helpful-container .was-helpful-thank-you {
+  padding: 0.625rem 1.25rem 0.625rem 1.25rem;
+}
+
+#was-helpful-thank-you {
+  visibility: hidden;
+}
+
+.helpful-container .helpful-question.yes-link,
+.helpful-container .helpful-question.no-link {
+  color: #8B34FC;
+  cursor: pointer;
+}
+
+.helpful-container .helpful-question.yes-link:hover,
+.helpful-container .helpful-question.no-link:hover {
+  background-color: #8B34FC;
+  color: #ffffff;
+}
diff --git a/docs/_templates/base.html b/docs/_templates/base.html
@@ -0,0 +1,76 @@
+{% extends '!base.html' %}
+{%- block extrahead -%}
+  {{ super() }}
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;700&family=IBM+Plex+Sans:ital,wght@0,400;0,700;1,400&display=swap" rel="stylesheet">
+  <link rel="modulepreload" href="https://unpkg.com/@qiskit/web-components/experimental-bundled-ui-shell.js">
+  <script type="module" src="https://unpkg.com/@qiskit/web-components/experimental-bundled-ui-shell.js"></script>
+  <style>
+    qiskit-ui-shell:not(:defined) {
+      display: block;
+      margin-bottom: 3.5rem;
+    }
+  </style>
+
+  {%- if analytics_enabled %}
+    <script>
+      (function () {
+        window._analytics = {
+          segment_key: 'ffdYLviQze3kzomaINXNk6NwpY9LlXcw',
+          coremetrics: false,
+          optimizely: false,
+          googleAddServices: false,
+          fullStory: false,
+          autoPageEventSpa: false,
+          autoFormEvents: false,
+          autoPageView: false
+        }
+
+        window.digitalData = {
+          page: {
+            pageInfo: {
+              productTitle: 'IBM Q Experience',
+              analytics: {
+                category: 'Qiskit.org'
+              }
+            }
+          }
+        }
+      }());
+    </script>
+    <script src="https://cloud.ibm.com/analytics/build/bluemix-analytics.min.js"></script>
+    <script>
+      (function () {
+        'use strict'
+
+        if (!window.bluemixAnalytics || !window.digitalData) { return }
+
+        const category = window.digitalData.page.pageInfo.analytics.category
+        const productTitle = window.digitalData.page.pageInfo.productTitle
+        const routeName = 'documentation'
+
+        window.bluemixAnalytics.pageEvent(category, routeName, {
+          navigationType: 'pushState',
+          productTitle: productTitle,
+          title: document.title
+        })
+
+        window.trackCta = (action) => {
+          if (!window.bluemixAnalytics || !window.digitalData) { return }
+
+          const category = window.digitalData.page.pageInfo.analytics.category
+          const productTitle = window.digitalData.page.pageInfo.productTitle
+
+          window.bluemixAnalytics.trackEvent('CTA Clicked', {
+            productTitle,
+            category,
+            CTA: action
+          })
+        }
+
+      }());
+    </script>
+  {%- endif -%}
+
+{%- endblock -%}
diff --git a/docs/_templates/page.html b/docs/_templates/page.html
@@ -0,0 +1,233 @@
+{% extends "base.html" %}
+
+{% block body -%}
+{{ super() }}
+{% include "partials/icons.html" %}
+
+<!-- QISKIT FURO CHANGE: start. Add our top nav bar. -->
+<qiskit-ui-shell variant="hide-account"></qiskit-ui-shell>
+<!-- QISKIT FURO CHANGE: end. -->
+
+<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation">
+<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc">
+<label class="overlay sidebar-overlay" for="__navigation">
+  <div class="visually-hidden">Hide navigation sidebar</div>
+</label>
+<label class="overlay toc-overlay" for="__toc">
+  <div class="visually-hidden">Hide table of contents sidebar</div>
+</label>
+
+{% if theme_announcement -%}
+<div class="announcement">
+  <aside class="announcement-content">
+    {% block announcement %} {{ theme_announcement }} {% endblock announcement %}
+  </aside>
+</div>
+{%- endif %}
+
+<div class="page">
+  <header class="mobile-header">
+    <div class="header-left">
+      <label class="nav-overlay-icon" for="__navigation">
+        <div class="visually-hidden">Toggle site navigation sidebar</div>
+        <i class="icon"><svg><use href="#svg-menu"></use></svg></i>
+      </label>
+    </div>
+    <div class="header-center">
+      <a href="{{ pathto(master_doc) }}"><div class="brand">{{ docstitle if docstitle else project }}</div></a>
+    </div>
+    <div class="header-right">
+      <div class="theme-toggle-container theme-toggle-header">
+        <button class="theme-toggle">
+          <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
+          <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
+          <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
+          <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
+        </button>
+      </div>
+      <label class="toc-overlay-icon toc-header-icon{% if furo_hide_toc %} no-toc{% endif %}" for="__toc">
+        <div class="visually-hidden">Toggle table of contents sidebar</div>
+        <i class="icon"><svg><use href="#svg-toc"></use></svg></i>
+      </label>
+    </div>
+  </header>
+  <aside class="sidebar-drawer">
+    <div class="sidebar-container">
+      {% block left_sidebar %}
+      <div class="sidebar-sticky">
+        {%- for sidebar_section in sidebars %}
+          {%- include sidebar_section %}
+        {%- endfor %}
+      </div>
+      {% endblock left_sidebar %}
+    </div>
+  </aside>
+  <div class="main">
+    <div class="content">
+      <div class="article-container">
+        <a href="#" class="back-to-top muted-link">
+          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+            <path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path>
+          </svg>
+          <span>{% trans %}Back to top{% endtrans %}</span>
+        </a>
+        <div class="content-icon-container">
+          {% if theme_top_of_page_button == "edit" -%}
+          {%- include "components/edit-this-page.html" with context -%}
+          {%- elif theme_top_of_page_button != None -%}
+          {{ warning("Got an unsupported value for 'top_of_page_button'") }}
+          {%- endif -%}
+          {#- Theme toggle -#}
+          <div class="theme-toggle-container theme-toggle-content">
+            <button class="theme-toggle">
+              <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
+              <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
+              <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
+              <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
+            </button>
+          </div>
+          <label class="toc-overlay-icon toc-content-icon{% if furo_hide_toc %} no-toc{% endif %}" for="__toc">
+            <div class="visually-hidden">Toggle table of contents sidebar</div>
+            <i class="icon"><svg><use href="#svg-toc"></use></svg></i>
+          </label>
+        </div>
+        <article role="main">
+          {% block content %}{{ body }}{% endblock %}
+        </article>
+      </div>
+      <footer>
+        {% block footer %}
+
+        <!-- QISKIT FURO CHANGE: start. Add user feedback to footer. -->
+        {% if analytics_enabled %}
+          <script>
+            function userFeedbackClicked(ctaType) {
+              document.getElementById('was-helpful-thank-you').style.visibility = 'visible';
+              window.trackCta(`Helpful - ${ctaType}`);
+            }
+          </script>
+            <hr class="helpful-hr hr-top" />
+            <div class="helpful-container">
+              <div class="helpful-question">Was this page helpful?</div>
+              <a class="helpful-question yes-link" onclick="userFeedbackClicked('yes')">Yes</a>
+              <a class="helpful-question no-link" onclick="userFeedbackClicked('no')">No</a>
+              <div class="was-helpful-thank-you" id="was-helpful-thank-you">Thank you!</div>
+            </div>
+            <hr class="helpful-hr hr-bottom"/>
+        {% endif %}
+        <!-- QISKIT FURO CHANGE: end. -->
+
+        <div class="related-pages">
+          {% if next -%}
+            <a class="next-page" href="{{ next.link }}">
+              <div class="page-info">
+                <div class="context">
+                  <span>{{ _("Next") }}</span>
+                </div>
+                <div class="title">{{ next.title }}</div>
+              </div>
+              <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+            </a>
+          {%- endif %}
+          {% if prev -%}
+            <a class="prev-page" href="{{ prev.link }}">
+              <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+              <div class="page-info">
+                <div class="context">
+                  <span>{{ _("Previous") }}</span>
+                </div>
+                {% if prev.link == pathto(master_doc) %}
+                <div class="title">{{ _("Home") }}</div>
+                {% else %}
+                <div class="title">{{ prev.title }}</div>
+                {% endif %}
+              </div>
+            </a>
+          {%- endif %}
+        </div>
+        <div class="bottom-of-page">
+          <div class="left-details">
+            {%- if show_copyright %}
+            <div class="copyright">
+              {%- if hasdoc('copyright') %}
+                {% trans path=pathto('copyright'), copyright=copyright|e -%}
+                  <a href="{{ path }}">Copyright</a> &#169; {{ copyright }}
+                {%- endtrans %}
+              {%- else %}
+                {% trans copyright=copyright|e -%}
+                  Copyright &#169; {{ copyright }}
+                {%- endtrans %}
+              {%- endif %}
+            </div>
+            {%- endif %}
+            {% trans %}Made with {% endtrans -%}
+            {%- if show_sphinx -%}
+            {% trans %}<a href="https://www.sphinx-doc.org/">Sphinx</a> and {% endtrans -%}
+            <a class="muted-link" href="https://pradyunsg.me">@pradyunsg</a>'s
+            {% endif -%}
+            {% trans %}
+            <a href="https://github.com/pradyunsg/furo">Furo</a>
+            {% endtrans %}
+            {%- if last_updated -%}
+            <div class="last-updated">
+              {% trans last_updated=last_updated|e -%}
+                Last updated on {{ last_updated }}
+              {%- endtrans -%}
+            </div>
+            {%- endif %}
+          </div>
+          <div class="right-details">
+            {% if theme_footer_icons or READTHEDOCS -%}
+            <div class="icons">
+              {% if theme_footer_icons -%}
+              {% for icon_dict in theme_footer_icons -%}
+              <a class="muted-link {{ icon_dict.class }}" href="{{ icon_dict.url }}" aria-label="{{ icon_dict.name }}">
+                {{- icon_dict.html -}}
+              </a>
+              {% endfor %}
+              {%- else -%}
+              {#- Show Read the Docs project -#}
+              {%- if READTHEDOCS and slug -%}
+              <a class="muted-link" href="https://readthedocs.org/projects/{{ slug }}" aria-label="On Read the Docs">
+                <svg x="0px" y="0px" viewBox="-125 217 360 360" xml:space="preserve">
+                  <path fill="currentColor" d="M39.2,391.3c-4.2,0.6-7.1,4.4-6.5,8.5c0.4,3,2.6,5.5,5.5,6.3 c0,0,18.5,6.1,50,8.7c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8c-0.1-4.2-3.6-7.5-7.8-7.4c-0.5,0-1,0.1-1.5,0.2 c0,0-28.1,3.5-50.9,1.6c-30.1-2.4-46.5-7.9-46.5-7.9C41.7,391.3,40.4,391.1,39.2,391.3z M39.2,353.6c-4.2,0.6-7.1,4.4-6.5,8.5 c0.4,3,2.6,5.5,5.5,6.3c0,0,18.5,6.1,50,8.7c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8c-0.1-4.2-3.6-7.5-7.8-7.4 c-0.5,0-1,0.1-1.5,0.2c0,0-28.1,3.5-50.9,1.6c-30.1-2.4-46.5-7.9-46.5-7.9C41.7,353.6,40.4,353.4,39.2,353.6z M39.2,315.9 c-4.2,0.6-7.1,4.4-6.5,8.5c0.4,3,2.6,5.5,5.5,6.3c0,0,18.5,6.1,50,8.7c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8 c-0.1-4.2-3.6-7.5-7.8-7.4c-0.5,0-1,0.1-1.5,0.2c0,0-28.1,3.5-50.9,1.6c-30.1-2.4-46.5-7.9-46.5-7.9 C41.7,315.9,40.4,315.8,39.2,315.9z M39.2,278.3c-4.2,0.6-7.1,4.4-6.5,8.5c0.4,3,2.6,5.5,5.5,6.3c0,0,18.5,6.1,50,8.7 c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8c-0.1-4.2-3.6-7.5-7.8-7.4c-0.5,0-1,0.1-1.5,0.2c0,0-28.1,3.5-50.9,1.6 c-30.1-2.4-46.5-7.9-46.5-7.9C41.7,278.2,40.4,278.1,39.2,278.3z M-13.6,238.5c-39.6,0.3-54.3,12.5-54.3,12.5v295.7 c0,0,14.4-12.4,60.8-10.5s55.9,18.2,112.9,19.3s71.3-8.8,71.3-8.8l0.8-301.4c0,0-25.6,7.3-75.6,7.7c-49.9,0.4-61.9-12.7-107.7-14.2 C-8.2,238.6-10.9,238.5-13.6,238.5z M19.5,257.8c0,0,24,7.9,68.3,10.1c37.5,1.9,75-3.7,75-3.7v267.9c0,0-19,10-66.5,6.6 C59.5,536.1,19,522.1,19,522.1L19.5,257.8z M-3.6,264.8c4.2,0,7.7,3.4,7.7,7.7c0,4.2-3.4,7.7-7.7,7.7c0,0-12.4,0.1-20,0.8 c-12.7,1.3-21.4,5.9-21.4,5.9c-3.7,2-8.4,0.5-10.3-3.2c-2-3.7-0.5-8.4,3.2-10.3c0,0,0,0,0,0c0,0,11.3-6,27-7.5 C-16,264.9-3.6,264.8-3.6,264.8z M-11,302.6c4.2-0.1,7.4,0,7.4,0c4.2,0.5,7.2,4.3,6.7,8.5c-0.4,3.5-3.2,6.3-6.7,6.7 c0,0-12.4,0.1-20,0.8c-12.7,1.3-21.4,5.9-21.4,5.9c-3.7,2-8.4,0.5-10.3-3.2c-2-3.7-0.5-8.4,3.2-10.3c0,0,11.3-6,27-7.5 C-20.5,302.9-15.2,302.7-11,302.6z M-3.6,340.2c4.2,0,7.7,3.4,7.7,7.7s-3.4,7.7-7.7,7.7c0,0-12.4-0.1-20,0.7 c-12.7,1.3-21.4,5.9-21.4,5.9c-3.7,2-8.4,0.5-10.3-3.2c-2-3.7-0.5-8.4,3.2-10.3c0,0,11.3-6,27-7.5C-16,340.1-3.6,340.2-3.6,340.2z" />
+                </svg>
+              </a>
+              {%- endif -%}
+              {#- Show GitHub repository home -#}
+              {%- if READTHEDOCS and display_github and github_user != "None" and github_repo != "None" -%}
+              <a class="muted-link" href="https://github.com/{{ github_user }}/{{ github_repo }}" aria-label="On GitHub">
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                  <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+              </a>
+              {%- endif -%}
+              {%- endif %}
+            </div>
+            {%- endif %}
+          </div>
+        </div>
+        {% endblock footer %}
+      </footer>
+    </div>
+    <aside class="toc-drawer{% if furo_hide_toc %} no-toc{% endif %}">
+      {% block right_sidebar %}
+      {% if not furo_hide_toc %}
+      <div class="toc-sticky toc-scroll">
+        <div class="toc-title-container">
+          <span class="toc-title">
+            {{ _("On this page") }}
+          </span>
+        </div>
+        <div class="toc-tree-container">
+          <div class="toc-tree">
+            {{ toc }}
+          </div>
+        </div>
+      </div>
+      {% endif %}
+      {% endblock right_sidebar %}
+    </aside>
+  </div>
+</div>
+{%- endblock %}
diff --git a/docs/_templates/versions.html → docs/_templates/sidebar/languages.html b/docs/_templates/versions.html → docs/_templates/sidebar/languages.html
@@ -1,29 +1,16 @@
-<!-- This file actually lives in the qiskit/qiskit repository but it is also
-provided here for testing the language selector. -->
+{% if translations_list %}
 <div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
   <span class="rst-current-version" data-toggle="rst-current-version">
-    <span class="rst-current-version-label">{{ version_label }}</span>
+    <span class="rst-current-version-label">{{ language_label }}</span>
     <span class="rst-versions-dropdown-icon"></span>
   </span>
   <div class="rst-other-versions">
-    {% if translations %}
     <dl>
       <dt>{{ _('Languages') }}</dt>
       {% for code, language in translations_list %}
         <dd><a class="version" href="{{ translation_url(code, pagename) }}">{{ language }}</a></dd>
       {% endfor %}
     </dl>
-    {% endif %}
-    <!-- Uncomment the following and for demo purposes. -->
-    <!--
-    <dl>
-      <dt>Languages</dt>
-      <dd><a class="version" href="#">English</a></dd>
-      <dd><a class="version" href="#">Japanese</a></dd>
-      <dd><a class="version" href="#">Korean</a></dd>
-      <dd><a class="version" href="#">Spanish</a></dd>
-    </dl>
-    -->
   </div>
   <script>
     jQuery('.version').click((evt) => {
@@ -34,3 +21,4 @@
     })
   </script>
 </div>
+{% endif %}
diff --git a/docs/_templates/sidebar/version_list.html b/docs/_templates/sidebar/version_list.html
@@ -0,0 +1,8 @@
+{% if version_list %}
+    <div class="sidebar-l1-expandable">Previous Releases</div>
+    <div class="sidebar-subheadings">
+        {% for version in version_list | sort(reverse=True) %}
+            <div class="sidebar-l2"><a href="/documentation/stable/{{ version }}/index.html">{{ version }}</a></div>
+        {% endfor %}
+    </div>
+{% endif %}