Modify Sphinx theme to use Qualtran theme colors and icons

dev_tools/requirements/deps/docs.txt

@@ -2,6 +2,7 @@ ipywidgets
 nbconvert
 nbformat
 sphinx
+sphinx-autobuild
 pydata-sphinx-theme
 myst-nb
-tensorflow-docs~=2023.5.24
+tensorflow-docs~=2023.5.24

dev_tools/requirements/envs/docs.env.txt

@@ -25,6 +25,8 @@ anyio==4.9.0
     #   -c envs/dev.env.txt
     #   httpx
     #   jupyter-server
+    #   starlette
+    #   watchfiles
 anywidget==0.9.18
     # via
     #   -c envs/dev.env.txt
@@ -107,7 +109,7 @@ cachetools==5.5.2
     #   -c envs/dev.env.txt
     #   -r deps/runtime.txt
     #   pennylane
-certifi==2025.1.31
+certifi==2025.4.26
     # via
     #   -c envs/dev.env.txt
     #   httpcore
@@ -130,6 +132,11 @@ click==8.1.8
     #   -c envs/dev.env.txt
     #   flask
     #   jupyter-cache
+    #   uvicorn
+colorama==0.4.6
+    # via
+    #   -c envs/dev.env.txt
+    #   sphinx-autobuild
 comm==0.2.2
     # via
     #   -c envs/dev.env.txt
@@ -151,7 +158,7 @@ cytoolz==1.0.1
     # via
     #   -c envs/dev.env.txt
     #   quimb
-dash==3.0.3
+dash==3.0.4
     # via
     #   -c envs/dev.env.txt
     #   -r deps/runtime.txt
@@ -226,11 +233,12 @@ greenlet==3.2.1
     # via
     #   -c envs/dev.env.txt
     #   sqlalchemy
-h11==0.14.0
+h11==0.16.0
     # via
     #   -c envs/dev.env.txt
     #   httpcore
-httpcore==1.0.8
+    #   uvicorn
+httpcore==1.0.9
     # via
     #   -c envs/dev.env.txt
     #   httpx
@@ -249,7 +257,7 @@ imagesize==1.4.1
     # via
     #   -c envs/dev.env.txt
     #   sphinx
-importlib-metadata==8.6.1
+importlib-metadata==8.7.0
     # via
     #   -c envs/dev.env.txt
     #   dash
@@ -260,7 +268,7 @@ ipykernel==6.29.5
     #   -c envs/dev.env.txt
     #   jupyterlab
     #   myst-nb
-ipython==8.35.0
+ipython==8.36.0
     # via
     #   -c envs/dev.env.txt
     #   -r deps/runtime.txt
@@ -311,7 +319,7 @@ jsonschema[format-nongpl]==4.23.0
     #   jupyter-events
     #   jupyterlab-server
     #   nbformat
-jsonschema-specifications==2024.10.1
+jsonschema-specifications==2025.4.1
     # via
     #   -c envs/dev.env.txt
     #   jsonschema
@@ -355,7 +363,7 @@ jupyter-server-terminals==0.5.3
     # via
     #   -c envs/dev.env.txt
     #   jupyter-server
-jupyterlab==4.4.0
+jupyterlab==4.4.1
     # via
     #   -c envs/dev.env.txt
     #   notebook
@@ -429,7 +437,7 @@ myst-parser==4.0.1
     # via
     #   -c envs/dev.env.txt
     #   myst-nb
-narwhals==1.35.0
+narwhals==1.37.1
     # via
     #   -c envs/dev.env.txt
     #   plotly
@@ -467,7 +475,7 @@ networkx==3.4.2
     #   -r deps/runtime.txt
     #   cirq-core
     #   pennylane
-notebook==7.4.0
+notebook==7.4.1
     # via
     #   -c envs/dev.env.txt
     #   -r deps/runtime.txt
@@ -588,12 +596,12 @@ pycparser==2.22
     # via
     #   -c envs/dev.env.txt
     #   cffi
-pydantic==2.11.3
+pydantic==2.11.4
     # via
     #   -c envs/dev.env.txt
     #   bartiq
     #   qref
-pydantic-core==2.33.1
+pydantic-core==2.33.2
     # via
     #   -c envs/dev.env.txt
     #   pydantic
@@ -753,6 +761,11 @@ sphinx==8.1.3
     #   myst-nb
     #   myst-parser
     #   pydata-sphinx-theme
+    #   sphinx-autobuild
+sphinx-autobuild==2024.10.3
+    # via
+    #   -c envs/dev.env.txt
+    #   -r deps/docs.txt
 sphinxcontrib-applehelp==2.0.0
     # via
     #   -c envs/dev.env.txt
@@ -785,6 +798,10 @@ stack-data==0.6.3
     # via
     #   -c envs/dev.env.txt
     #   ipython
+starlette==0.46.2
+    # via
+    #   -c envs/dev.env.txt
+    #   sphinx-autobuild
 sympy==1.12.1
     # via
     #   -c envs/dev.env.txt
@@ -882,6 +899,7 @@ typing-extensions==4.13.2
     #   referencing
     #   sqlalchemy
     #   typing-inspection
+    #   uvicorn
 typing-inspection==0.4.0
     # via
     #   -c envs/dev.env.txt
@@ -898,6 +916,14 @@ urllib3==2.4.0
     # via
     #   -c envs/dev.env.txt
     #   requests
+uvicorn==0.34.2
+    # via
+    #   -c envs/dev.env.txt
+    #   sphinx-autobuild
+watchfiles==1.0.5
+    # via
+    #   -c envs/dev.env.txt
+    #   sphinx-autobuild
 wcwidth==0.2.13
     # via
     #   -c envs/dev.env.txt
@@ -915,6 +941,10 @@ websocket-client==1.8.0
     # via
     #   -c envs/dev.env.txt
     #   jupyter-server
+websockets==15.0.1
+    # via
+    #   -c envs/dev.env.txt
+    #   sphinx-autobuild
 werkzeug==3.0.6
     # via
     #   -c envs/dev.env.txt

docs/Makefile

@@ -1,18 +1,48 @@
-# Minimal makefile for Sphinx documentation
+# Copyright 2025 Google LLC
 #
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+######## Configuration ########
 
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
-BUILDDIR      = _build
+# Before we go any further, test if certain programs are available.
+PROGRAMS_NEEDED = sphinx-build sphinx-autobuild
+TEST := $(foreach p,$(PROGRAMS_NEEDED),\
+	  $(if $(shell which $(p)),_,$(error Cannot find program "$(p)")))
+
+# The first two can be overridden via env vars.
+SPHINXOPTS     ?=
+SPHINXBUILD    ?= sphinx-build
+SPHINXAUTO     = sphinx-autobuild
+SPHINXAUTOOPTS = --open-browser -j auto
+SOURCEDIR      = .
+BUILDDIR       = _build
+
+.PHONY: help Makefile
+
+######## Targets ########
 
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+auto autobuild live livehtml:
+	@$(SPHINXAUTO) "$(SOURCEDIR)" "$(BUILDDIR)"/html $(SPHINXOPTS) $(SPHINXAUTOOPTS) $(O)
+
+# The next one is for working on a theme, when it's best to disable incremental builds using "-a".
+# The build times are much slower, but CSS and template changes are picked up, and that's critical.
+# C.f. https://github.com/sphinx-doc/sphinx-autobuild#working-on-a-sphinx-html-theme
+auto-dev:
+	@$(SPHINXAUTO) -a "$(SOURCEDIR)" "$(BUILDDIR)"/html $(SPHINXOPTS) $(SPHINXAUTOOPTS) $(O)
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

docs/_static/fixes.css

@@ -13,4 +13,10 @@ table.fixed.responsive {
 table.tfo-notebook-buttons.tfo-api {
     width: 100%;
     margin-bottom: 1.5em;
-}
+}
+
+/* Adjust size of GitHub icon in the nav bar.
+ */
+html .pst-navbar-icon {
+  font-size: 1.5rem;
+}

docs/_static/qai-theme.css

@@ -0,0 +1,58 @@
+/* Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+:root {
+  --qai-color-blue-500: #4285f4;
+  --qai-color-blue-700: #1967d2;
+
+  --qai-color-magenta-400: #d367c4;
+  --qai-color-magenta-500: #b356cd;
+  --qai-color-magenta-700: #7c42c0;
+}
+
+html[data-theme="light"] {
+  /* The primary color is used as the unvisited link color. */
+  --pst-color-primary: var(--qai-color-blue-700);
+  --pst-color-secondary: var(--qai-color-blue-500);
+
+  /* Color inline code is for `backtick text`. */
+  --pst-color-inline-code: var(--qai-color-magenta-700);
+  --pst-color-inline-code-links: var(--qai-color-magenta-500);
+
+  /* Some code boxes have an accent color on the left border. */
+  --mystnb-source-margin-color: var(--qai-color-magenta-700);
+}
+
+a[data-theme=light]:hover {
+  color: var(--qai-color-blue-700);
+}
+
+
+html[data-theme=dark] {
+  /* The primary color is used as the unvisited link color. */
+  --pst-color-primary: var(--qai-color-blue-500);
+  --pst-color-secondary: var(--qai-color-blue-700);
+
+  /* Color inline code is for `backtick text`. */
+  --pst-color-inline-code: var(--qai-color-magenta-400);
+  --pst-color-inline-code-links: var(--qai-color-magenta-500);
+
+  /* Some code boxes have an accent color on the left border. */
+  --mystnb-source-margin-color: var(--qai-color-magenta-700);
+}
+
+a[data-theme=dark]:hover {
+  color: var(--qai-color-blue-700);
+}

docs/_templates/qai_logo.html

@@ -0,0 +1,4 @@
+<a href="https://quantumai.google">
+  <img height="40em" alt="Google Quantum AI"
+       src="https://raw.githubusercontent.com/quantumlib/Qualtran/8fa2e8ae4fa071ece632fb7a7f615918128983e3/docs/_static/quantum-ai.svg">
+</a>

docs/_templates/qualtran-sidebar.html

@@ -0,0 +1,16 @@
+{# Displays the TOC-subtree for pages nested under the currently active top-level TOCtree element. #}
+<nav class="bd-docs-nav bd-links"
+     aria-label="{{ title }}">
+  <p class="bd-links__title" role="heading" aria-level="1">{{ title }}</p>
+  <div class="bd-toc-item navbar-nav">
+    {{- generate_toctree_html(
+      "sidebar",
+      show_nav_level=theme_show_nav_level | int,
+      maxdepth=theme_navigation_depth | int,
+      collapse=theme_collapse_navigation | tobool,
+      includehidden=theme_sidebar_includehidden | tobool,
+      titles_only=True
+      )
+    -}}
+  </div>
+</nav>

docs/conf.py

@@ -47,10 +47,36 @@
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
-
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'pydata_sphinx_theme'
+html_theme_options = {
+    "navbar_start": ["navbar-logo"],
+    "navbar_center": ["navbar-nav"],
+    "navbar_end": ["navbar-icon-links", "theme-switcher"],
+    "icon_links": [
+        {
+            "name": "GitHub repository",
+            "url": "https://github.com/quantumlib/Qualtran",
+            "icon": "fab fa-github-square",
+            "type": "fontawesome",
+        }
+    ],
+    "footer_center": ["qai_logo"],
+}
+
+# qualtran-sidebar.html replaces the default sidebar title 'Section navigation'
+# with the appropriate section title.
+html_sidebars = {
+    "bloq_infra": ["qualtran-sidebar"],
+    "bloqs/index": ["qualtran-sidebar"],
+    "reference/index": ["qualtran-sidebar"],
+}
+
 html_static_path = ['_static']
-html_css_files = ['fixes.css']
+html_css_files = ['fixes.css', 'qai-theme.css']
+html_logo = 'https://raw.githubusercontent.com/quantumlib/Qualtran/refs/heads/main/docs/_static/qualtran-logo-mode-sensitive.svg'
+html_favicon = (
+    'https://raw.githubusercontent.com/quantumlib/Qualtran/refs/heads/main/docs/_static/favicon.png'
+)