Remove Pytorch theme (#576)

Closes #571. Thanks
to @arnaucasau, no projects are actively using the old Pytorch theme 🎉

A follow up will also remove the `qiskit` theme so that we only have
`qiskit-ecosystem`.

.github/workflows/main.yml

@@ -36,11 +36,6 @@ jobs:
 
       - name: Create artifacts/ folder
         run: mkdir artifacts
-      - name: Build Legacy Pytorch theme
-        run: |
-          tox run -e pytorch
-          tar -zcvf pytorch_html_docs.tar.gz example_docs/docs/_pytorch_build
-          mv pytorch_html_docs.tar.gz artifacts/.
       - name: Build Qiskit (Furo) theme
         run: |
           tox run -e qiskit

CONTRIBUTING.md

@@ -19,7 +19,6 @@ There are a few important subfolders to be aware of:
 This subfolder contains the HTML, CSS, and Python files that are used for the Qiskit themes. It has these folders:
 
 * `assets`: CSS and JavaScript for the `qiskit` theme.
-* `pytorch`: all the code for the legacy Pytorch theme (`qiskit_sphinx_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.
 
@@ -28,7 +27,7 @@ The top-level Python files are used for logic used by the theme, such as `transl
 ### `/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`, `example_docs/docs/_ecosystem_build`, and `example_docs/docs/_pytorch_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/_qiskit_build` and `example_docs/docs/_ecosystem_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
@@ -45,9 +44,6 @@ We use [Tox](https://tox.wiki/en/latest/), which you will need to install global
 * 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/` with the legacy Pytorch theme:
-  1. `tox -e pytorch`
-  2. Open up `example_docs/docs/_pytorch_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.
@@ -115,15 +111,13 @@ We use web components from https://github.com/Qiskit/web-components to include c
 To update the top nav bar web component:
 
 1. In https://github.com/Qiskit/web-components, run `npm install` then `npm run build`.
-2. There should be a file created at the root of the web components repository called `experimental-bundled-ui-shell.js`. Copy its contents into these files in this theme repository:
-   1. `src/qiskit_sphinx_theme/pytorch/static/js/web-components/top-nav-bar.js`
-   2. `src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/static/js/web-components/top-nav-bar.js`
-3. Build the example docs with `tox -e qiskit` and `tox -e pytorch` to ensure everything works.
+2. There should be a file created at the root of the web components repository called `experimental-bundled-ui-shell.js`. Copy its contents into `src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/static/js/web-components/top-nav-bar.js`
+3. Build the example docs with `tox -e qiskit` to ensure everything works.
 
 If you want to add a new web component:
 
 1. Work with the web components repository's team to set up `npm run build` to generate a single JavaScript file.
-2. Add the file contents to the `src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/static/js/web-components/` folder in this theme repository. (We shouldn't add web components to Pytorch.)
+2. Add the file contents to the `src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/static/js/web-components/` folder in this theme repository.
 3. Load the web component in `extra_head.html` with a line like `<script src="{{ pathto('_static/js/web-components/my-component.js', 1) }}"></script>`.
 4. Use the web component element in the relevant HTML, e.g. `<my-component>` in `layout.html`. Remember to surround the change with a `QISKIT CHANGE:` comment.
 5. Build the example docs with `tox -e qiskit` to ensure everything works.

README.md

@@ -1,11 +1,11 @@
 # qiskit-sphinx-theme
-The Sphinx themes for Qiskit and Qiskit Ecosystem documentation.
+The Sphinx theme for Qiskit Ecosystem documentation.
 
 ### Warning: new theme migration
 
-In qiskit-sphinx-theme 1.13, we added the new `qiskit` theme, which migrates from Pytorch to Furo for several improvements. qiskit-sphinx-theme 1.14 added the `qiskit-ecosystem` theme. The old Pytorch theme will be removed in qiskit-sphinx-theme 2.0, which we expect to release in July or August 2023.
+In qiskit-sphinx-theme 1.14, we replaced the old `qiskit_sphinx_theme` based on Pytorch with the new `qiskit-ecosystem` theme based on Furo. The old theme was removed in qiskit-sphinx-theme 2.0.
 
-See the section [Migrate from old Pytorch theme to new theme](#migrate-from-old-pytorch-theme-to-new-theme) for migration instructions.
+See [Migrate from old Pytorch theme to new theme](https://github.com/Qiskit/qiskit_sphinx_theme/blob/1.16/README.md#migrate-from-old-pytorch-theme-to-new-theme) for migration instructions.
 
 ## Overview
 
@@ -205,49 +205,6 @@ html_theme_options = {
 }
 ```
 
-## Migrate from old Pytorch theme to new theme
-
-In qiskit-sphinx-theme 1.13, we migrated to a new Sphinx theme called `qiskit`, which is based on Furo from the pip, Black, and attrs documentation. See https://github.com/Qiskit/qiskit_sphinx_theme/issues/232 for the motivation. qiskit-sphinx-theme 1.14 added the `qiskit-ecosystem` theme for Ecosystem projects.
-
-qiskit-sphinx-theme 1.13+ continues to support the legacy Pytorch theme, but support will be removed in version 2.0.
-
-To migrate, in `conf.py`:
-
-1. Ensure that `"qiskit_sphinx_theme"` is in the `extensions` list.
-2. Set `html_theme = "qiskit-ecosystem"` rather than `"qiskit_sphinx_theme"`. (`qiskit` should only be used by Qiskit Terra.)
-3. Remove all `html_theme_options`.
-4. Remove `expandable_sidebar` from `html_context`, if set. If it was set, follow the below section [How to migrate expandable_sidebar](#how-to-migrate-expandable_sidebar).
-
-Render the docs and check that everything looks how expected. If not, please open a GitHub issue or reach out on Slack for help.
-
-### How to migrate expandable_sidebar
-
-With the old theme, to have expandable folders, you had to have a dedicated `.. toctree ::` directive with a `:caption:` option, like this:
-
-```rst
-.. toctree::
-  :caption: My Folder
-  :hidden:
-
-  Page 1 <page1>
-  Page 2 <page2>
-```
-
-Instead, the new theme will render the `:caption:` as a top-level section header in the left sidebar, with top-level entries for each page. See the screenshot in the PR description of https://github.com/Qiskit/qiskit_sphinx_theme/pull/384 for an example of how the old theme renders `:caption:` and compare to [the new theme](tests/js/qiskit.test.js-snapshots/left-side-bar-renders-correctly-1-linux.png).
-
-Additionally, the new theme renders pages with their own subpages as expandable folders, unlike the old theme. [For example](tests/js/qiskit.test.js-snapshots/left-side-bar-renders-correctly-1-linux.png), `<apidocs/index>` will include all subpages that are listed in the `.. toctree ::` of the page `apidocs/index.rst`.
-
-So, when migrating, you have to decide which behavior you want:
-
-- Use the new theme's style. No changes necessary.
-- Use the new theme's style, but get rid of the top level section header. To implement:
-  1. Consolidate the `.. toctree ::` directive with earlier ones so that they are all in the same `toctree`.
-- Keep the `:caption:` as an expandable folder, rather than a top-level section header. To implement:
-  1. Create a new directory and RST file like `my_folder/index.rst`.
-  2. Move the `.. toctree::` directive to that page.
-  3. Get rid of the `:caption:` option.
-  4. Link to the new file `my_folder/index.rst` in the parent `index.rst` by adding it to a `.. toctree ::` in the parent.
-
 ## Tip: suggested site structure
 
 To keep UX/UI similar across different Qiskit packages, we encourage the following structure for you sidebar, which can be set in the toctree of your `index.rst`:

example_docs/docs/conf.py

@@ -59,20 +59,12 @@
 # for interpolation, i.e. Sphinx doesn't have built-in interpolation.
 html_title = f"{project} {release}"
 
-# This allows us to test both the Furo and Pytorch themes. In normal repositories, `html_theme`
+# 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
 
-if _THEME == "qiskit_sphinx_theme":
-    html_theme_options = {
-        "logo_only": True,
-        "display_version": True,
-        "prev_next_buttons_location": "bottom",
-    }
-    # Sets a better style for code syntax highlighting.
-    pygments_style = "colorful"
-elif _THEME == "qiskit-ecosystem":
+if _THEME == "qiskit-ecosystem":
     # This tests out that ecosystem projects can change the color scheme.
     # Only specific IBM projects should set this! Most Ecosystem projects
     # should use the default of purple.

pyproject.toml

@@ -27,15 +27,12 @@ dependencies = [
     "docutils",
     # Keep in sync with Furo's constraint.
     "sphinx>=6.0",
-    # Remove jQuery once we get rid of the Pytorch theme.
-    "sphinxcontrib-jquery",
     # See CONTRIBUTING.md for how to upgrade Furo.
     "furo==2023.8.19",
 ]
 
 [project.entry-points."sphinx.html_themes"]
 qiskit = "qiskit_sphinx_theme"
-qiskit_sphinx_theme = "qiskit_sphinx_theme"
 qiskit-ecosystem = "qiskit_sphinx_theme"
 
 [project.urls]

src/qiskit_sphinx_theme/__init__.py

@@ -68,8 +68,6 @@ def remove_thebe_if_not_needed(
 
 
 def activate_furo(app: sphinx.application.Sphinx, config: sphinx.config.Config) -> None:
-    if config.html_theme == "qiskit_sphinx_theme":
-        return
     # We set a low priority so that our Qiskit CSS file overrides Furo.
     app.add_css_file("styles/furo.css", 100)
     app.add_js_file("scripts/qiskit-sphinx-theme.js")
@@ -92,11 +90,6 @@ def setup(app: sphinx.application.Sphinx) -> dict[str, bool]:
     # Used to generate URL references. Expected to be e.g. `ecosystem/finance`.
     app.add_config_value("docs_url_prefix", default=None, rebuild="html", types=[str])
 
-    # Sphinx 6 stopped including jQuery by default. Our Pytorch theme depend on jQuery,
-    # so activate it for our users automatically. Unfortunately, we can't make this activation
-    # conditional based on which theme is chosen.
-    app.setup_extension("sphinxcontrib.jquery")
-
     # We always activate these plugins, but they are only used when users:
     # * use the directives in their RST,
     # * set `translations_list` in conf.py, or
@@ -105,7 +98,6 @@ def setup(app: sphinx.application.Sphinx) -> dict[str, bool]:
     previous_releases.setup(app)
     translations.setup(app)
 
-    app.add_html_theme("qiskit_sphinx_theme", _get_theme_absolute_path("pytorch"))
     app.add_html_theme("qiskit", _get_theme_absolute_path("theme/qiskit-sphinx-theme"))
     app.add_html_theme("qiskit-ecosystem", _get_theme_absolute_path("ecosystem"))