From 11eb12cab3a97787eb5fe41a23c1f77ad9b5d3d3 Mon Sep 17 00:00:00 2001 From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> Date: Fri, 1 Dec 2023 11:43:55 -0500 Subject: [PATCH] Remove "was this page useful" mechanism (analytics) (#579) Qiskit documentation now lives in docs.quantum.ibm.com and has its own analytics mechanism. The Qiskit Ecosystem projects will be migrating to GitHub pages. https://github.com/Qiskit/ecosystem/issues/578. Given that, I doubt we'll want to commit to still maintaining this analytics mechanism. Maintenance is more than only the code: it also means committing to helping projects access the dashboard. Instead, keep this Sphinx theme as simple as possible to make it more sustainable. Projects highly interested in analytics could always add the functionality their own way. --- CONTRIBUTING.md | 2 +- README.md | 16 ----- example_docs/docs/conf.py | 5 -- .../assets/styles/_footer.scss | 42 ------------ .../assets/styles/qiskit-sphinx-theme.scss | 1 - src/qiskit_sphinx_theme/ecosystem/page.html | 12 +--- .../custom_templates/extra_head.html | 60 ------------------ .../custom_templates/footer_analytics.html | 28 -------- .../theme/qiskit-sphinx-theme/page.html | 4 -- tests/js/ecosystem.test.js | 10 --- .../colors-can-be-changed-footer-1-linux.png | Bin 12778 -> 0 bytes tests/js/qiskit.test.js | 25 -------- ...footer-includes-page-analytics-1-linux.png | Bin 12787 -> 0 bytes ...ank-you-when-analytics-clicked-1-linux.png | Bin 3886 -> 0 bytes 14 files changed, 4 insertions(+), 201 deletions(-) delete mode 100644 src/qiskit_sphinx_theme/assets/styles/_footer.scss delete mode 100644 src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/custom_templates/footer_analytics.html delete mode 100644 tests/js/ecosystem.test.js-snapshots/colors-can-be-changed-footer-1-linux.png delete mode 100644 tests/js/qiskit.test.js-snapshots/footer-includes-page-analytics-1-linux.png delete mode 100644 tests/js/qiskit.test.js-snapshots/footer-says-thank-you-when-analytics-clicked-1-linux.png diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6b7a75c6..80fa282c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -94,7 +94,7 @@ The docs will rebuild every time you run `npm run test-qiskit` and `npm run test First, get the `snapshot_results` folder, either by downloading it from CI or by running the tests locally. Then: -1. Find the "actual" snapshot for the failing test, such as `footer-includes-page-analytics-1-actual.png`. +1. Find the "actual" snapshot for the failing test, such as `api-docs-class-page-1-actual.png`. 2. Copy that snapshot into the folder `tests/js/qiskit.test.js-snapshots` or `tests/js/ecosystem.test.js-snapshots`, depending on which theme failed. Rename the `-actual.png` file ending to be `-linux.png` and overwrite the prior file. ### How to add a new snapshot diff --git a/README.md b/README.md index 1d90e32f..cbed0557 100644 --- a/README.md +++ b/README.md @@ -116,22 +116,6 @@ The `qiskit_sphinx_theme` extension defines the below custom directives for you ![](tests/js/qiskit.test.js-snapshots/custom-directives-1-linux.png) ![](tests/js/qiskit.test.js-snapshots/custom-directives-2-linux.png) -## Enable Qiskit.org Analytics - -Qiskit.org uses Segment Analytics to collect information on traffic to sites under the qiskit.org domain. This is not enabled by default but if you would like to enable it you can add a `analytics_enabled` variable to the `html_context` object in your `conf.py`. Setting this to `True` will enable analytics for your site once it is deployed to `qiskit.org/`. - -```python -html_context = { - 'analytics_enabled': True -} -``` - -By enabling analytics we will be able to collect information on number of visits to each documentation page. It will also trigger the addition of a `Was this page helpful?` component at the bottom of each documentation page, so users will be able to provide yes/no feedback for each page. - -![](tests/js/qiskit.test.js-snapshots/footer-includes-page-analytics-1-linux.png) - -If you do not enable analytics, no data will be collected and the `Was this page helpful?` component will not show. - ## 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 diff --git a/example_docs/docs/conf.py b/example_docs/docs/conf.py index 91f6b104..a3cb136f 100644 --- a/example_docs/docs/conf.py +++ b/example_docs/docs/conf.py @@ -75,14 +75,9 @@ } html_context = { - # Add "Was this page useful?" to the footer. - "analytics_enabled": True, # Users of the theme can set prior version numbers. They'll # show up in the sidebar under the "Previous Versions" section. "version_list": [0.1, 0.2, 0.3], - # 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", diff --git a/src/qiskit_sphinx_theme/assets/styles/_footer.scss b/src/qiskit_sphinx_theme/assets/styles/_footer.scss deleted file mode 100644 index ac37d1c2..00000000 --- a/src/qiskit_sphinx_theme/assets/styles/_footer.scss +++ /dev/null @@ -1,42 +0,0 @@ -/* 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. - */ - -.qiskit-analytics-container { - display: inline-flex; - border-top: 1px solid var(--color-background-border); - border-bottom: 1px solid var(--color-background-border); - color: var(--color-foreground-secondary); - - margin-bottom: 1rem; - - div, - a { - padding: 0.625rem 1.25rem 0.625rem 1.25rem; - } - - a { - color: var(--color-brand-primary); - cursor: pointer; - text-decoration: none; - - &:hover { - background-color: var(--color-brand-primary); - color: #ffffff; - } - } - -} - -#qiskit-analytics-thank-you { - visibility: hidden; -} diff --git a/src/qiskit_sphinx_theme/assets/styles/qiskit-sphinx-theme.scss b/src/qiskit_sphinx_theme/assets/styles/qiskit-sphinx-theme.scss index fc1fcfb8..8bf1b9ec 100644 --- a/src/qiskit_sphinx_theme/assets/styles/qiskit-sphinx-theme.scss +++ b/src/qiskit_sphinx_theme/assets/styles/qiskit-sphinx-theme.scss @@ -17,7 +17,6 @@ @import "colors"; @import "custom-directives"; @import "drop-shadows"; -@import "footer"; @import "icons"; @import "layout"; @import "left-sidebar"; diff --git a/src/qiskit_sphinx_theme/ecosystem/page.html b/src/qiskit_sphinx_theme/ecosystem/page.html index 82bf44c3..a48e8e51 100644 --- a/src/qiskit_sphinx_theme/ecosystem/page.html +++ b/src/qiskit_sphinx_theme/ecosystem/page.html @@ -1,11 +1,9 @@ {#- This file is vendored from Furo (created by Pradyun Gedam) and used under the MIT license. - When adding custom Qiskit code, surround it with `QISKIT CHANGE: start` and - `QISKIT CHANGE: end` Jinja-style comments. - - We also vendor this file in the Qiskit theme. When making changes, check if `theme/page.html` - should have it too. + No changes should be made to it. This file is only to overwrite the changes made + in the Qiskit theme. Once that theme is deleted, this file should be deleted so + that we can go back to using the default file from Furo. -#} {% extends "base.html" %} @@ -104,10 +102,6 @@