diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index de8e4e7b..f20ddd7d 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -17,6 +17,8 @@ jobs:
- uses: actions/checkout@v3
with:
fetch-depth: 0
+ - name: Fix permissions for sphinx-theme-builder
+ run: chown -R $(id -u):$(id -g) .
- name: Set up Node.js
uses: actions/setup-node@v3
with:
diff --git a/.gitignore b/.gitignore
index 3f9949e6..534a5613 100644
--- a/.gitignore
+++ b/.gitignore
@@ -134,3 +134,8 @@ dmypy.json
# JavaScript
/node_modules
/snapshot_results
+/.nodeenv/
+
+# These get copied from sphinx-theme-builder.
+/src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/static/styles
+/src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/static/scripts
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0e94f051..11106c5e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -16,9 +16,13 @@ contributing to qiskit_sphinx_theme, these are documented below.
There are a few important subfolders to be aware of:
### `/src`
-This subfolder contains the raw HTML, CSS, and Python files that are used to set the framework for Qiskit documentation web pages. The files in this folder will set the styles when a project calls the `qiskit_sphinx_theme` in its `conf.py`, unless the project overrides the style with their own files.
+This subfolder contains the HTML, CSS, and Python files that are used for the Qiskit themes. It has these folders:
-E.g. if a qiskit project (with the `qiskit_sphinx_theme` installed) wants to override any of the themes files (such as the `layout.html`) that the `qiskit_sphinx_theme` provides it needs to have its own version of that file (e.g. `layout.html`) stored in its `docs/_templates` folder.
+* `assets`: CSS and JavaScript for our Furo theme, which is the future of the Sphinx theme.
+* `pytorch`: all the code for the legacy Pytorch theme.
+* `theme`: static files, like HTML templates, for our Furo theme.
+
+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.
@@ -102,13 +106,13 @@ 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/furo/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 docs` and `THEME=_qiskit_furo tox -e docs` 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/furo/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. (We shouldn't add web components to Pytorch.)
3. Load the web component in `extra_head.html` with a line like ``.
4. Use the web component element in the relevant HTML, e.g. `` in `layout.html`. Remember to surround the change with a `QISKIT CHANGE:` comment.
5. Build the example docs with `THEME=_qiskit_furo tox -e docs` to ensure everything works.
@@ -129,7 +133,7 @@ Contributors with write access can also use live previews of the docs: GitHub wi
------
## FYI: How Furo Theme Inheritance Works
-We use Sphinx's inheritance future for our Furo theme, which we set in `furo/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 use Sphinx's inheritance future for our Furo 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.
@@ -149,10 +153,10 @@ When making changes, use those comments to make clear where and what we changed.
{#- QISKIT CHANGE: end. -#}
```
-If the change is greater than 1-3 lines, write the code in a new file in `custom_templates`, then use Jinja's `include` directive, as shown in the example right above.
+If the change is greater than 1-3 lines, write the code in a new file in `theme/qiskit-sphinx-theme/custom_templates`, then use Jinja's `include` directive, as shown in the example right above.
### How to change CSS
-Make CSS changes in the file `qiskit_changes.css`. It takes precedence over any CSS rules from Furo.
+Make CSS changes in the file `assets/styles/qiskit-sphinx-theme.css`. It takes precedence over any CSS rules from Furo.
When adding changes, document the rationale unless the code is already self-documenting and obvious. Group similar changes into sections.
@@ -164,7 +168,7 @@ Update the version in `pyproject.toml`. Always pin to an exact version of Furo.
However, when updating, closely analyze each commit in the release to check for any changes that would break our fork. We want to make sure that our HTML files are always in sync with Furo. If they have made any changes, then add them back to our copy of the file.
### How to add an icon
-Edit the file `furo/partials/icons.html`. Copy the HTML code of the `` tags and add them as the first element within the `` tag. Don't forget to include the `id` attribute, which will serve as the name associated with the icon.
+Edit the file `theme/qiskit-sphinx-theme/partials/icons.html`. Copy the HTML code of the `` tags and add them as the first element within the `` tag. Don't forget to include the `id` attribute, which will serve as the name associated with the icon.
To use the icon, reference it with `#`.
diff --git a/MANIFEST.in b/MANIFEST.in
deleted file mode 100644
index de667ce4..00000000
--- a/MANIFEST.in
+++ /dev/null
@@ -1,4 +0,0 @@
-recursive-include src *.html
-recursive-include src theme.conf
-graft src/qiskit_sphinx_theme/furo/static
-graft src/qiskit_sphinx_theme/pytorch/static
diff --git a/package.json b/package.json
index 0c0fcd14..69b75435 100644
--- a/package.json
+++ b/package.json
@@ -7,6 +7,7 @@
"playwright": "^1.34.3"
},
"scripts": {
+ "build": "mkdir src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/static/styles; cp src/qiskit_sphinx_theme/assets/styles/qiskit-sphinx-theme.css src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/static/styles/qiskit-sphinx-theme.css",
"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 .",
diff --git a/pyproject.toml b/pyproject.toml
index 11efb4f7..481f35c1 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
[build-system]
-requires = ["setuptools"]
-build-backend = "setuptools.build_meta"
+requires = ["sphinx-theme-builder>=0.2.0b2"]
+build-backend = "sphinx_theme_builder"
[project]
name = "qiskit-sphinx-theme"
@@ -40,6 +40,9 @@ _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"]
diff --git a/src/qiskit_sphinx_theme/__init__.py b/src/qiskit_sphinx_theme/__init__.py
index 8038e0ba..f81d1312 100644
--- a/src/qiskit_sphinx_theme/__init__.py
+++ b/src/qiskit_sphinx_theme/__init__.py
@@ -15,13 +15,12 @@
from pathlib import Path
from typing import TYPE_CHECKING
-import sphinx.addnodes
-
from qiskit_sphinx_theme import directives, previous_releases, translations
if TYPE_CHECKING:
import sphinx.addnodes
import sphinx.application
+ import sphinx.config
__version__ = "1.12.0rc1"
__version_full__ = __version__
@@ -68,6 +67,17 @@ def remove_thebe_if_not_needed(
]
+def activate_themes(app: sphinx.application.Sphinx, config: sphinx.config.Config) -> None:
+ if config.html_theme == "_qiskit_furo":
+ # 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/furo.js")
+ 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")
+
+
# See https://www.sphinx-doc.org/en/master/development/theming.html
def setup(app: sphinx.application.Sphinx) -> dict[str, bool]:
# Used to generate URL references. Expected to be e.g. `ecosystem/finance`.
@@ -82,26 +92,9 @@ 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("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")
+ app.connect("config-inited", activate_themes)
return {"parallel_read_safe": True, "parallel_write_safe": True}
diff --git a/src/qiskit_sphinx_theme/assets/scripts/qiskit-sphinx-theme.js b/src/qiskit_sphinx_theme/assets/scripts/qiskit-sphinx-theme.js
new file mode 100644
index 00000000..cf6e54c2
--- /dev/null
+++ b/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.
diff --git a/src/qiskit_sphinx_theme/furo/static/styles/qiskit_changes.css b/src/qiskit_sphinx_theme/assets/styles/qiskit-sphinx-theme.css
similarity index 100%
rename from src/qiskit_sphinx_theme/furo/static/styles/qiskit_changes.css
rename to src/qiskit_sphinx_theme/assets/styles/qiskit-sphinx-theme.css
diff --git a/src/qiskit_sphinx_theme/furo/base.html b/src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/base.html
similarity index 100%
rename from src/qiskit_sphinx_theme/furo/base.html
rename to src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/base.html
diff --git a/src/qiskit_sphinx_theme/furo/custom_templates/extra_head.html b/src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/custom_templates/extra_head.html
similarity index 100%
rename from src/qiskit_sphinx_theme/furo/custom_templates/extra_head.html
rename to src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/custom_templates/extra_head.html
diff --git a/src/qiskit_sphinx_theme/furo/custom_templates/footer_analytics.html b/src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/custom_templates/footer_analytics.html
similarity index 100%
rename from src/qiskit_sphinx_theme/furo/custom_templates/footer_analytics.html
rename to src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/custom_templates/footer_analytics.html
diff --git a/src/qiskit_sphinx_theme/furo/custom_templates/sidebar_languages.html b/src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/custom_templates/sidebar_languages.html
similarity index 100%
rename from src/qiskit_sphinx_theme/furo/custom_templates/sidebar_languages.html
rename to src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/custom_templates/sidebar_languages.html
diff --git a/src/qiskit_sphinx_theme/furo/custom_templates/sidebar_search.html b/src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/custom_templates/sidebar_search.html
similarity index 100%
rename from src/qiskit_sphinx_theme/furo/custom_templates/sidebar_search.html
rename to src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/custom_templates/sidebar_search.html
diff --git a/src/qiskit_sphinx_theme/furo/custom_templates/sidebar_version_list.html b/src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/custom_templates/sidebar_version_list.html
similarity index 100%
rename from src/qiskit_sphinx_theme/furo/custom_templates/sidebar_version_list.html
rename to src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/custom_templates/sidebar_version_list.html
diff --git a/src/qiskit_sphinx_theme/furo/page.html b/src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/page.html
similarity index 100%
rename from src/qiskit_sphinx_theme/furo/page.html
rename to src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/page.html
diff --git a/src/qiskit_sphinx_theme/furo/partials/icons.html b/src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/partials/icons.html
similarity index 100%
rename from src/qiskit_sphinx_theme/furo/partials/icons.html
rename to src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/partials/icons.html
diff --git a/src/qiskit_sphinx_theme/furo/static/images/logo.png b/src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/static/images/logo.png
similarity index 100%
rename from src/qiskit_sphinx_theme/furo/static/images/logo.png
rename to src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/static/images/logo.png
diff --git a/src/qiskit_sphinx_theme/furo/static/js/web-components/top-nav-bar.js b/src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/static/js/web-components/top-nav-bar.js
similarity index 100%
rename from src/qiskit_sphinx_theme/furo/static/js/web-components/top-nav-bar.js
rename to src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/static/js/web-components/top-nav-bar.js
diff --git a/src/qiskit_sphinx_theme/furo/theme.conf b/src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/theme.conf
similarity index 66%
rename from src/qiskit_sphinx_theme/furo/theme.conf
rename to src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/theme.conf
index 80097a39..47eacb46 100644
--- a/src/qiskit_sphinx_theme/furo/theme.conf
+++ b/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 =
custom_templates/sidebar_search.html,
diff --git a/tests/py/web_components_test.py b/tests/py/web_components_test.py
index 071c5ff6..d2116d0a 100644
--- a/tests/py/web_components_test.py
+++ b/tests/py/web_components_test.py
@@ -4,9 +4,9 @@
def test_top_nav_bar():
- furo = Path("src/qiskit_sphinx_theme/furo/static/js/web-components/top-nav-bar.js").read_text(
- "utf-8"
- )
+ furo = Path(
+ "src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/static/js/web-components/top-nav-bar.js"
+ ).read_text("utf-8")
pytorch = Path(
"src/qiskit_sphinx_theme/pytorch/static/js/web-components/top-nav-bar.js"
).read_text("utf-8")