Merge branch 'main' of github.com:Qiskit/qiskit_sphinx_theme into EA/…

…left-chevron

.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:

.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

CONTRIBUTING.md

@@ -15,15 +15,19 @@ contributing to qiskit_sphinx_theme, these are documented below.
 
 There are a few important subfolders to be aware of:
 
-### `/qiskit_sphinx_theme`
-This subfolder contains the raw html and css 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.
+### `/src`
+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. 
 
-It pulls styles from the `/qiskit_sphinx_theme` subfolder. You can check any changes you are making to the `qiskit_sphinx_theme` by building the documentation (see running locally section) and opening the html files generated in `/example_docs/docs/_build/html`.
+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/html`.
 
 ### `/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
@@ -101,14 +105,14 @@ 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. `qiskit_sphinx_theme/pytorch_base/static/js/web-components/top-nav-bar.js`
-   2. `qiskit_sphinx_theme/furo/base/static/js/web-components/top-nav-bar.js`
+   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 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 `qiskit_sphinx_theme/furo/base/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 `<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 `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/base/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,23 +153,22 @@ 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.
 
 You can change [Furo's CSS variable values](https://github.com/pradyunsg/furo/tree/main/src/furo/assets/styles/variables) by setting them in the `body` rule at the top. When introducing our own CSS variables, prefix it with `--qiskit` for clarity, e.g. `--qiskit-top-nav-bar-height`.
 
 ### How to update the Furo version
-Update the version in `setup.py`. Always pin to an exact version of Furo.
+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/base/partials/icons.html`. Copy the HTML code of the `<svg></svg>` tags and add them as the first element within the `<symbol>` 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 `<svg></svg>` tags and add them as the first element within the `<symbol>` 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 `#`.
 
@@ -188,7 +191,7 @@ The release process changes whether you are releasing the very first `rc1` for t
    1. `git checkout main`
    2. `git pull upstream main`
    3. `git checkout -b release-<version-number>`, e.g. `release-1.11.0rc1`
-   4. Bump `setup.py` and `qiskit_sphinx_theme/__init__.py` to use the new version, e.g. https://github.com/Qiskit/qiskit_sphinx_theme/pull/207
+   4. Bump `src/qiskit_sphinx_theme/__init__.py` to use the new version, e.g. https://github.com/Qiskit/qiskit_sphinx_theme/pull/207
    5. PR the change and land it
 2. Push the Git tag:
    1. `git checkout main`
@@ -222,7 +225,7 @@ Use this process for:
    1. `git checkout <release-branch>`, e.g. `1.11`.
    2. `git pull upstream <release-branch>`, e.g. `1.11`.
    3. `git checkout -b release-<full-version>`, e.g. `release-1.11.0rc3`
-   4. Bump `setup.py` and `qiskit_sphinx_theme/__init__.py` to use the new version, e.g. https://github.com/Qiskit/qiskit_sphinx_theme/pull/207
+   4. Bump `src/qiskit_sphinx_theme/__init__.py` to use the new version, e.g. https://github.com/Qiskit/qiskit_sphinx_theme/pull/207
    5. PR the change and land it. Change the PR's merge base in the top to the release branch; it defaults to `main`.
 3. Push the Git tag:
    1. `git checkout <release-branch>`, e.g. `1.11`.
@@ -242,4 +245,4 @@ Use this process for:
       1. Add the sections `**Features / API Changes:**` and `**Bug Fixes:**`. 
       2. Use `git log --oneline` to see what changes have been made. Copy and paste those entries as bullets into the relevant sections. Ignore any "internal only" changes like CI changes or updates to the README.
       3. Preview the release notes with the "Preview" tab.
-   3. Click "Publish release"
+   3. Click "Publish release"

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 .",

pyproject.toml

@@ -1,12 +1,52 @@
 [build-system]
-requires = ["setuptools"]
-build-backend = "setuptools.build_meta"
+requires = ["sphinx-theme-builder>=0.2.0b2"]
+build-backend = "sphinx_theme_builder"
 
-[tool.pytest.ini_options]
-addopts = [
-    "--import-mode=importlib",
+[project]
+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 = "hello@qiskit.org" }]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Topic :: Internet",
+    "Topic :: Software Development :: Documentation",
+    "Framework :: Sphinx :: Theme",
 ]
 
+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.5.20",
+]
+
+[project.entry-points."sphinx.html_themes"]
+qiskit_sphinx_theme = "qiskit_sphinx_theme"
+_qiskit_furo = "qiskit_sphinx_theme"
+
+[project.urls]
+"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"]
+
 [tool.black]
 line-length = 100
 target-version = ["py37", "py38", "py39", "py310", "py311"]

qiskit_sphinx_theme/__init__.py → src/qiskit_sphinx_theme/__init__.py

@@ -10,20 +10,17 @@
 # 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
 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__
@@ -70,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`.
@@ -83,27 +91,10 @@ 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_base"))
-    app.add_html_theme("_qiskit_furo", _get_theme_absolute_path("furo/base"))
+    app.add_html_theme("qiskit_sphinx_theme", _get_theme_absolute_path("pytorch"))
+    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}

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.

qiskit_sphinx_theme/furo/base/static/styles/qiskit_changes.css → src/qiskit_sphinx_theme/assets/styles/qiskit-sphinx-theme.css

@@ -129,17 +129,6 @@ html {
   scroll-behavior: auto;
 }
 
-/* Without this, long titles break the site. This is especially a problem in API docs.
-*  Remove if https://github.com/pradyunsg/furo/pull/670 gets merged and released. */
-h1,
-h2,
-h3,
-h4,
-h5,
-h6 {
-  overflow-wrap: break-word;
-}
-
 /* ------------------------------------------------------------------------------
 * Top nav bar
 * ------------------------------------------------------------------------------- */
@@ -385,6 +374,30 @@ div.header-left svg use {
   text-transform: uppercase;
 }
 
+/* ------------------------------------------------------------------------------
+* Typography
+* ------------------------------------------------------------------------------- */
+
+/* Without this, long titles break the site. This is especially a problem in API docs.
+*  Remove if https://github.com/pradyunsg/furo/pull/670 gets merged and released. */
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  overflow-wrap: break-word;
+}
+
+/* Carbon only uses bold for the smallest headers:
+*  https://carbondesignsystem.com/guidelines/typography/type-sets/ */
+h1,
+h2,
+h3,
+h4 {
+  font-weight: 400;
+}
+
 /* ---------------------------------------------------------------------------
 * Drop shadows and border-radius
 * ---------------------------------------------------------------------------- */

qiskit_sphinx_theme/furo/base/custom_templates/extra_head.html → src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/custom_templates/extra_head.html

@@ -1,6 +1,12 @@
 <link rel="preconnect" href="https://fonts.googleapis.com">
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;700&family=IBM+Plex+Sans:ital,wght@0,400;0,700;1,400&display=swap" rel="stylesheet">
+{#- Per https://carbondesignsystem.com/guidelines/typography/overview, this loads these fonts with
+weights 400 and 600:
+  * IBM Plex Mono
+  * IBM Plex Sans
+  * IBM Plex Sans italics
+-#}
+<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;600&family=IBM+Plex+Sans:ital,wght@0,400;0,600;1,400;1,600&display=swap" rel="stylesheet">
 <script src="{{ pathto('_static/js/web-components/top-nav-bar.js', 1) }}"></script>
 <script>
   {#- Force light mode. -#}

src/qiskit_sphinx_theme/theme/qiskit-sphinx-theme/custom_templates/sidebar_search.html

@@ -0,0 +1,8 @@
+{#- This file is vendored from Furo's sidebars/search.html. Its only change is to the `placeholder`
+for the search `input` element to include the project name. -#}
+<form class="sidebar-search-container" method="get" action="{{ pathto('search') }}" role="search">
+  <input class="sidebar-search" placeholder="Search {{ project }} docs" name="q" aria-label="{{ _("Search" ) }}">
+  <input type="hidden" name="check_keywords" value="yes">
+  <input type="hidden" name="area" value="default">
+</form>
+<div id="searchbox"></div>