Set up sphinx-theme-builder

.gitignore

@@ -134,3 +134,4 @@ dmypy.json
 # JavaScript
 /node_modules
 /snapshot_results
+/.nodeenv/

package.json

@@ -7,6 +7,7 @@
     "playwright": "^1.34.3"
   },
   "scripts": {
+    "build": ":",
     "start": "http-server example_docs/docs/_build/html",
     "test-snapshots": "npm run _docker-build && npm run _docker-run",
     "_docker-build": "docker build -t qiskit_sphinx_theme -f tests/js/Dockerfile .",

pyproject.toml

@@ -1,11 +1,12 @@
 [build-system]
-requires = ["setuptools"]
-build-backend = "setuptools.build_meta"
+requires = ["sphinx-theme-builder>=0.2.0b2"]
+build-backend = "sphinx_theme_builder"
 
 [project]
-version = "1.12.0rc1"
-name = "qiskit_sphinx_theme"
+name = "qiskit-sphinx-theme"
 description = "A Sphinx theme for Qiskit and Qiskit Ecosystem projects"
+dynamic = ["version"]
+
 license = { text = "Apache 2" }
 authors = [{ name = "Qiskit Development Team", email = "[email protected]" }]
 classifiers = [
@@ -39,6 +40,10 @@ _qiskit_furo = "qiskit_sphinx_theme"
 "Bug Tracker" = "https://github.com/Qiskit/qiskit_sphinx_theme/issues"
 "Source Code" = "https://github.com/Qiskit/qiskit_sphinx_theme"
 
+[tool.sphinx-theme-builder]
+node-version = "18.16.0"
+
+
 [tool.pytest.ini_options]
 addopts = ["--import-mode=importlib"]
 

src/qiskit_sphinx_theme/__init__.py

@@ -10,8 +10,6 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Pytorch Sphinx theme."""
-
 from __future__ import annotations
 
 from pathlib import Path
@@ -84,26 +82,16 @@ def setup(app: sphinx.application.Sphinx) -> dict[str, bool]:
     translations.setup(app)
 
     app.add_html_theme("qiskit_sphinx_theme", _get_theme_absolute_path("pytorch"))
-    app.add_html_theme("_qiskit_furo", _get_theme_absolute_path("theme/furo"))
+    app.add_html_theme("_qiskit_furo", _get_theme_absolute_path("theme/qiskit-sphinx-theme"))
 
     app.connect("html-page-context", remove_thebe_if_not_needed)
 
-    if app.config.html_theme == "_qiskit_furo":
-        # The below must be kept in sync with `furo/__init__.py`.
-        from furo import (
-            WrapTableAndMathInAContainerTransform,
-            _builder_inited,
-            _html_page_context,
-            _overwrite_pygments_css,
-        )
-
-        app.add_post_transform(WrapTableAndMathInAContainerTransform)
-        app.connect("html-page-context", _html_page_context)
-        app.connect("builder-inited", _builder_inited)
-        app.connect("build-finished", _overwrite_pygments_css)
-    else:
-        # Sphinx 6 stopped including jQuery by default. Our Pytorch theme depend on jQuery,
-        # so activate it for our users automatically.
-        app.setup_extension("sphinxcontrib.jquery")
+    # TODO: figure out how to make this conditional.
+    app.add_css_file("styles/furo.css", 100)
+    app.add_js_file("scripts/furo.js")
+
+    # Sphinx 6 stopped including jQuery by default. Our Pytorch theme depend on jQuery,
+    # so activate it for our users automatically.
+    app.setup_extension("sphinxcontrib.jquery")
 
     return {"parallel_read_safe": True, "parallel_write_safe": True}

src/qiskit_sphinx_theme/assets/scripts/qiskit-sphinx-theme.js

@@ -0,0 +1,4 @@
+// Empty file required by sphinx-theme-builder.
+//
+// This will allow us to fix Furo's JavaScript code to workaround
+// https://github.com/Qiskit/qiskit_sphinx_theme/issues/368.

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

@@ -0,0 +1,3 @@
+/* Empty file required by sphinx-theme-builder.
+
+This will be replaced by Sass code that gets compiled. */

src/qiskit_sphinx_theme/theme/furo/theme.conf → src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/theme.conf

@@ -1,11 +1,6 @@
 [theme]
 inherit = furo
-
-# Our stylesheet takes precedence.
-stylesheet =
-  styles/furo.css,
-  styles/furo-extensions.css,
-  styles/qiskit_changes.css
+stylesheet = styles/qiskit-sphinx-theme.css
 
 sidebars =
   sidebar/search.html,