Remove qiskit theme (#585)

Closes #577.

This allows us to greatly simplify the repository. Now we only have a
single theme, whereas before we had 3 themes so had to generalize a
bunch of logic like our visual regression testing.

Author: Eric-Arellano

.github/workflows/main.yml

@@ -6,7 +6,7 @@ jobs:
     runs-on: ubuntu-latest
     if: github.repository_owner == 'Qiskit'
     container:
-      # Keep in sync with tests/js/Dockerfile.base's base image.
+      # Keep in sync with tests/js/Dockerfile's base image.
       image: mcr.microsoft.com/playwright:v1.34.0-jammy
     steps:
       - uses: actions/checkout@v3
@@ -36,16 +36,11 @@ jobs:
 
       - name: Create artifacts/ folder
         run: mkdir artifacts
-      - name: Build Qiskit (Furo) theme
-        run: |
-          tox run -e qiskit
-          tar -zcvf qiskit_html_docs.tar.gz example_docs/docs/_qiskit_build
-          mv qiskit_html_docs.tar.gz artifacts/.
       - name: Build Ecosystem theme
         run: |
-          tox run -e ecosystem
-          tar -zcvf ecosystem_html_docs.tar.gz example_docs/docs/_ecosystem_build
-          mv ecosystem_html_docs.tar.gz artifacts/.
+          tox run -e docs
+          tar -zcvf html_docs.tar.gz example_docs/docs/_build
+          mv html_docs.tar.gz artifacts/.
       - name: Upload Sphinx builds
         uses: actions/upload-artifact@v3
         if: always()
@@ -55,8 +50,7 @@ jobs:
 
       - name: Run visual regression tests
         run: |
-          npm run _run-qiskit-tests
-          npm run _run-ecosystem-tests
+          npm run _run-tests
       - name: Upload snapshot results
         if: failure()
         uses: actions/upload-artifact@v3

CONTRIBUTING.md

@@ -1,9 +1,6 @@
 # Contributing
 
-First read the overall Qiskit project contributing guidelines. These are all
-included in the qiskit documentation:
-
-https://qiskit.org/documentation/contributing_to_qiskit.html
+First read the overall [Qiskit project contributing guidelines](https://github.com/Qiskit/qiskit/blob/main/CONTRIBUTING.md#).
 
 ## Contributing to qiskit_sphinx_theme
 
@@ -16,18 +13,17 @@ contributing to qiskit_sphinx_theme, these are documented below.
 There are a few important subfolders to be aware of:
 
 ### `/src`
-This subfolder contains the HTML, CSS, and Python files that are used for the Qiskit themes. It has these folders:
+This subfolder contains the HTML, CSS, and Python files that are used for the `qiskit-ecosystem` theme. It has these folders:
 
-* `assets`: CSS and JavaScript for the `qiskit` theme.
-* `ecosystem`: the code for the `qiskit-ecosystem` theme, which is built on top of the base `qiskit` theme. This folder only has overrides.
-* `theme`: static files, like HTML templates, for the `qiskit` theme.
+* `assets`: CSS
+* `theme`: HTML templates and the `theme.conf` config file
 
 The top-level Python files are used for logic used by the theme, such as `translations.py` determining what URLs the HTML should use for translations support.
 
 ### `/example_docs`
 This subfolder contains a scaled down version of the Sphinx build that builds the documentation for the Qiskit repos. 
 
-It pulls styles from the `/src` subfolder. You can check any changes you are making to theme by building the documentation (see running locally section) and opening the HTML files generated in `example_docs/docs/_qiskit_build` and `example_docs/docs/_ecosystem_build`.
+It pulls styles from the `/src` subfolder. You can check any changes you are making to theme by building the documentation (see running locally section) and opening the HTML files generated in `example_docs/docs/_build`.
 
 ### `/docs_guide`
 This subfolder contains guidance on how to write documentation and build sphinx projects for Qiskit and Qiskit Ecosystem projects. You can view the fully rendered docs guide at https://qisk.it/docs-guide
@@ -38,18 +34,15 @@ This subfolder contains guidance on how to write documentation and build sphinx
 We use [Tox](https://tox.wiki/en/latest/), which you will need to install globally (e.g. using [`pipx`](https://pypa.github.io/pipx/)).
 
 * Run Python tests: `tox -e py`
-* Build `example_docs/` with the `qiskit` theme:
-  1. `tox -e qiskit`
-  2. Open up `example_docs/docs/_qiskit_build/index.html` in your browser
-* Build `example_docs/` with the `qiskit-ecosystem` theme:
-  1. `tox -e ecosystem`
-  2. Open up `example_docs/docs/_ecosystem_build/index.html` in your browser
+* Build `example_docs/`:
+  1. `tox -e docs`
+  2. Open up `example_docs/docs/_build/index.html` in your browser
 * Build `docs_guide`:
   1. `tox -e docs-guide`
   2. Open up `docs_guide/_build/html/index.html` in your browser.
 * Run doctests for the docs guide: `tox -e doctest`
 
-Sometimes Sphinx's caching can get in a bad state. First, try running `tox -e clean`, which will remove Sphinx's cache. If you are still having issues, try adding `-r` your command, e.g. `tox -e qiskit -r`. `-r` tells Tox to reinstall the dependencies.
+Sometimes Sphinx's caching can get in a bad state. First, try running `tox -e clean`, which will remove Sphinx's cache. If you are still having issues, try adding `-r` your command, e.g. `tox -e docs -r`. `-r` tells Tox to reinstall the dependencies.
 
 ------
 ## Visual regression testing
@@ -85,21 +78,21 @@ First, you need to install:
 Then, to run the tests locally:
 
 1. `npm install`
-2. `npm run test-qiskit` or `npm run test-ecosystem`, depending on which theme you want.
+2. `npm run test`.
    * Warning: the very first time you run the tests, they will fail because the `snapshot-results` folder will not yet exist. Try running again.
 
-The docs will rebuild every time you run `npm run test-qiskit` and `npm run test-ecosystem`.
+The docs will rebuild every time you run `npm run test`.
 
 ### How to update the expected snapshot for intentional changes
 
 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 `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.
+2. Copy that snapshot into the folder `tests/js/tests.js-snapshots`. Rename the `-actual.png` file ending to be `-linux.png` and overwrite the prior file.
 
 ### How to add a new snapshot
 
-Copy the tests in `qiskit.test.js` or `ecosystem.test.js` for inspiration. Make sure the selector you use in `page.locator()` is accurate. Title the tests with a useful but concise description of what you're testing.
+Copy the tests in `tests.js` for inspiration. Make sure the selector you use in `page.locator()` is accurate. Title the tests with a useful but concise description of what you're testing.
 
 Then, run the tests either locally or in CI to generate the snapshots. When running locally, the files will be added automatically. When using CI, follow the section [How to update the expected snapshot for intentional changes](#how-to-update-the-expected-snapshot-for-intentional-changes).
 
@@ -110,19 +103,16 @@ We upload the docs builds to CI. So, you can download what the site will look li
 
 1. Navigate to the GitHub Actions page for the "Tests" action.
 2. Open the "Summary" page with the house icon.
-3. Under the "Artifacts" section, there should be a "html_docs" entry. Download it.
-4. Choose the theme you want, such as `qiskit_html_docs.tar.gz`, and un-tar it. Then, open the `index.html` page in a browser.
+3. Under the "Artifacts" section, there should be a "html_docs" entry. Download it. Un-tar it, then open the `index.html` page in a browswer.
 
 Contributors with write access can also use live previews of the docs: GitHub will deploy a website using your changes. To use live previews, push your branch to `upstream` rather than your fork. GitHub will leave a comment with the link to the site. Please prefix your branch name with your initials, e.g. `EA/add-translations`, for good Git hygiene.
 
 ------
 ## FYI: How Furo Theme Inheritance Works
 
-We use Sphinx's inheritance future for our Furo-based `qiskit` theme, which we set in `theme/qiskit-sphinx-theme/theme.conf`. Sphinx will default to using all the files from Furo. But if we have a file with the same name as Furo, then Sphinx will use our copy. That allows us to override only what we care about.
-
-We try to keep changes to a minimum because every divergence we make from base Furo increases our maintenance burden. Hence we prioritise only making changes that are important to the Qiskit brand. If the change would be generally useful to other users of Furo, we try to contribute upstream to the Furo project itself.
+We use Sphinx's inheritance feature because our theme is built on top of [Furo](https://github.com/pradyunsg/furo). The `furo` inheritance is configured in `theme/qiskit-sphinx-theme/theme.conf`. Sphinx will default to using all the files from Furo. But if we have a file with the same name as Furo, then Sphinx will use our copy. That allows us to override only what we care about.
 
-The `qiskit-ecosystem` theme then inherits the `qiskit` theme to make some tweaks, although we're removing the `qiskit` theme so the themes are converging.
+We try to keep changes to a minimum because every divergence we make from base Furo increases our maintenance burden. Hence we prioritise only making changes that are important to the Qiskit Ecosystem brand. If the change would be generally useful to other users of Furo, we try to contribute upstream to the Furo project itself.
 
 ### How to change HTML
 Copy the HTML template from Furo and save it in the same file path. Then, at the top of the file, add this header:

Dockerfile

@@ -27,7 +27,7 @@ WORKDIR /app
 
 COPY . .
 
-RUN tox run -e qiskit
+RUN tox run -e docs
 
 EXPOSE 8000
-CMD ["python", "-m", "http.server", "-d", "example_docs/docs/_qiskit_build"]
+CMD ["python", "-m", "http.server", "-d", "example_docs/docs/_build"]

README.md

@@ -10,14 +10,14 @@ See [Migrate from old Pytorch theme to new theme](https://github.com/Qiskit/qisk
 ## Overview
 
 This repository hosts three things: 
-- Qiskit Sphinx themes (located in the `src/` folder)
-- Example Docs (located in the `example_docs/` folder)
+- `qiskit-ecosystem` theme (located in the `src/` folder)
+- example docs (located in the `example_docs/` folder)
 - Qiskit Docs Guide (located in the `docs_guide/` folder)
 
-The Qiskit Sphinx Themes are the themes used by Qiskit Documentation (https://qiskit.org/documentation/) and Qiskit Ecosystem projects.
+The `qiskit-ecosystem` theme is used by projects in the [Qiskit Ecosystem](https://qiskit.github.io/ecosystem).
 
-The Example Docs is a minimal Sphinx project that is used for testing the Qiskit Sphinx Theme. Every
-pull request will trigger [a GitHub workflow](https://github.com/Qiskit/qiskit_sphinx_theme/blob/main/.github/workflows/main.yml) that builds the Example Docs to make sure the changes do
+The example docs are a minimal Sphinx project that is used for testing the Qiskit Sphinx Theme. Every
+pull request will trigger [a GitHub workflow](https://github.com/Qiskit/qiskit_sphinx_theme/blob/main/.github/workflows/main.yml) that builds the example docs to make sure the changes do
 not introduce unintended changes.
 
 The Qiskit Docs Guide hosts instructions, guidelines and recommendations of good documentation
@@ -34,7 +34,7 @@ pip install qiskit-sphinx-theme
 
 Then, set up the theme by updating `conf.py`:
 
-1. Set `html_theme = "qiskit-ecosystem"` (only Qiskit Terra should use `qiskit`)
+1. Set `html_theme = "qiskit-ecosystem"`
 2. Add `"qiskit_sphinx_theme"` to `extensions`
 
 You also likely want to set `html_title` in `conf.py`. This results in the left sidebar having a more useful and concise name, along with the page title in the browser. Most projects will want to use this in their `conf.py`:

example_docs/docs/conf.py

@@ -22,6 +22,8 @@
 language = "en"
 release = "9.99"
 
+html_theme = "qiskit-ecosystem"
+
 # This allows including custom CSS and HTML templates.
 html_static_path = ["_static"]
 templates_path = ["_templates"]
@@ -58,11 +60,6 @@
 # for interpolation, i.e. Sphinx doesn't have built-in interpolation.
 html_title = f"{project} {release}"
 
-# This allows us to test both the Qiskit and Qiskit Ecosystem themes. In normal repositories, `html_theme`
-# would be set to one specific theme.
-_THEME = os.getenv("THEME", "qiskit")
-html_theme = _THEME
-
 html_context = {
     # Users of the theme can set prior version numbers. They'll
     # show up in the sidebar under the "Previous Versions" section.

package.json

@@ -15,11 +15,8 @@
   },
   "scripts": {
     "build": "webpack",
-    "start-qiskit": "http-server example_docs/docs/_qiskit_build -p 8080",
-    "start-ecosystem": "http-server example_docs/docs/_ecosystem_build -p 8081",
-    "test-qiskit": "tests/js/run_docker.py qiskit",
-    "test-ecosystem": "tests/js/run_docker.py ecosystem",
-    "_run-qiskit-tests": "THEME=qiskit playwright test",
-    "_run-ecosystem-tests": "THEME=ecosystem playwright test"
+    "start": "http-server example_docs/docs/_build -p 8080",
+    "test": "tests/js/run_docker.py",
+    "_run-tests": "playwright test"
   }
 }

playwright.config.js

@@ -13,23 +13,12 @@
 
 import { defineConfig } from "@playwright/test";
 
-let testMatch;
-let baseURL;
-let startCommand;
-if (process.env.THEME === "qiskit") {
-  testMatch = /.*qiskit.test.js/;
-  baseURL = "http://127.0.0.1:8080";
-  startCommand = "start-qiskit";
-} else {
-  testMatch = /.*ecosystem.test.js/;
-  baseURL = "http://127.0.0.1:8081";
-  startCommand = "start-ecosystem";
-}
+const baseURL = "http://127.0.0.1:8080"
 
 export default defineConfig({
   outputDir: "snapshot_results",
   workers: process.env.CI ? 1 : undefined,
-  testMatch,
+  testMatch: /.*tests\.js$/,
   expect: {
     toHaveScreenshot: {
       threshold: 0.01, // We expect colors to be near exact matches.
@@ -41,7 +30,7 @@ export default defineConfig({
     viewport: { width: 1920, height: 1080 },
   },
   webServer: {
-    command: `npm run ${startCommand}`,
+    command: "npm run start",
     url: baseURL,
   },
 });

pyproject.toml

@@ -32,7 +32,6 @@ dependencies = [
 ]
 
 [project.entry-points."sphinx.html_themes"]
-qiskit = "qiskit_sphinx_theme"
 qiskit-ecosystem = "qiskit_sphinx_theme"
 
 [project.urls]

src/qiskit_sphinx_theme/__init__.py

@@ -85,7 +85,6 @@ def setup(app: sphinx.application.Sphinx) -> dict[str, bool]:
     previous_releases.setup(app)
     translations.setup(app)
 
-    app.add_html_theme("qiskit", _get_theme_absolute_path("theme/qiskit-sphinx-theme"))
     app.add_html_theme("qiskit-ecosystem", _get_theme_absolute_path("theme/qiskit-sphinx-theme"))
 
     app.connect("config-inited", activate_furo)

tests/js/Dockerfile.base tests/js/Dockerfile

@@ -11,15 +11,12 @@
 # that they have been altered from the originals.
 
 
-# A base Dockerfile to run our snapshot tests locally. This is to avoid issues with CI and local
+# This Dockerfile allows us to run our snapshot tests locally. That avoids issues with CI and local
 # differing. In CI, we also run with the same base image.
 # See https://playwright.dev/docs/test-snapshots.
 #
 # Note that we build the Sphinx docs outside of this Docker image; we only need to run the
 # server inside Docker so that the docs are rendered the same locally and in CI.
-#
-# Each specific theme extends this base image to copy in the built docs and run their specific
-# project with Playwright.
 
 
 # Keep this base image in sync with .github/workflows/main.yml.
@@ -33,3 +30,6 @@ RUN npm ci
 # Copy over our tests.
 COPY playwright.config.js ./
 COPY tests/js tests/js
+
+COPY example_docs/docs/_build example_docs/docs/_build
+CMD [ "npm", "run", "_run-tests" ]