Skip to content

Commit 6960395

Browse files
mhuckamhucka
authored
Modify Sphinx theme to use Qualtran theme colors and icons (#1638)
1 parent 8fa2e8a commit 6960395

File tree

8 files changed

+195
-24
lines changed

8 files changed

+195
-24
lines changed

‎dev_tools/requirements/deps/docs.txt

+2-1
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ ipywidgets
22
nbconvert
33
nbformat
44
sphinx
5+
sphinx-autobuild
56
pydata-sphinx-theme
67
myst-nb
7-
tensorflow-docs~=2023.5.24
8+
tensorflow-docs~=2023.5.24

‎dev_tools/requirements/envs/docs.env.txt

+42-12
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ anyio==4.9.0
2525
# -c envs/dev.env.txt
2626
# httpx
2727
# jupyter-server
28+
# starlette
29+
# watchfiles
2830
anywidget==0.9.18
2931
# via
3032
# -c envs/dev.env.txt
@@ -107,7 +109,7 @@ cachetools==5.5.2
107109
# -c envs/dev.env.txt
108110
# -r deps/runtime.txt
109111
# pennylane
110-
certifi==2025.1.31
112+
certifi==2025.4.26
111113
# via
112114
# -c envs/dev.env.txt
113115
# httpcore
@@ -130,6 +132,11 @@ click==8.1.8
130132
# -c envs/dev.env.txt
131133
# flask
132134
# jupyter-cache
135+
# uvicorn
136+
colorama==0.4.6
137+
# via
138+
# -c envs/dev.env.txt
139+
# sphinx-autobuild
133140
comm==0.2.2
134141
# via
135142
# -c envs/dev.env.txt
@@ -151,7 +158,7 @@ cytoolz==1.0.1
151158
# via
152159
# -c envs/dev.env.txt
153160
# quimb
154-
dash==3.0.3
161+
dash==3.0.4
155162
# via
156163
# -c envs/dev.env.txt
157164
# -r deps/runtime.txt
@@ -226,11 +233,12 @@ greenlet==3.2.1
226233
# via
227234
# -c envs/dev.env.txt
228235
# sqlalchemy
229-
h11==0.14.0
236+
h11==0.16.0
230237
# via
231238
# -c envs/dev.env.txt
232239
# httpcore
233-
httpcore==1.0.8
240+
# uvicorn
241+
httpcore==1.0.9
234242
# via
235243
# -c envs/dev.env.txt
236244
# httpx
@@ -249,7 +257,7 @@ imagesize==1.4.1
249257
# via
250258
# -c envs/dev.env.txt
251259
# sphinx
252-
importlib-metadata==8.6.1
260+
importlib-metadata==8.7.0
253261
# via
254262
# -c envs/dev.env.txt
255263
# dash
@@ -260,7 +268,7 @@ ipykernel==6.29.5
260268
# -c envs/dev.env.txt
261269
# jupyterlab
262270
# myst-nb
263-
ipython==8.35.0
271+
ipython==8.36.0
264272
# via
265273
# -c envs/dev.env.txt
266274
# -r deps/runtime.txt
@@ -311,7 +319,7 @@ jsonschema[format-nongpl]==4.23.0
311319
# jupyter-events
312320
# jupyterlab-server
313321
# nbformat
314-
jsonschema-specifications==2024.10.1
322+
jsonschema-specifications==2025.4.1
315323
# via
316324
# -c envs/dev.env.txt
317325
# jsonschema
@@ -355,7 +363,7 @@ jupyter-server-terminals==0.5.3
355363
# via
356364
# -c envs/dev.env.txt
357365
# jupyter-server
358-
jupyterlab==4.4.0
366+
jupyterlab==4.4.1
359367
# via
360368
# -c envs/dev.env.txt
361369
# notebook
@@ -429,7 +437,7 @@ myst-parser==4.0.1
429437
# via
430438
# -c envs/dev.env.txt
431439
# myst-nb
432-
narwhals==1.35.0
440+
narwhals==1.37.1
433441
# via
434442
# -c envs/dev.env.txt
435443
# plotly
@@ -467,7 +475,7 @@ networkx==3.4.2
467475
# -r deps/runtime.txt
468476
# cirq-core
469477
# pennylane
470-
notebook==7.4.0
478+
notebook==7.4.1
471479
# via
472480
# -c envs/dev.env.txt
473481
# -r deps/runtime.txt
@@ -588,12 +596,12 @@ pycparser==2.22
588596
# via
589597
# -c envs/dev.env.txt
590598
# cffi
591-
pydantic==2.11.3
599+
pydantic==2.11.4
592600
# via
593601
# -c envs/dev.env.txt
594602
# bartiq
595603
# qref
596-
pydantic-core==2.33.1
604+
pydantic-core==2.33.2
597605
# via
598606
# -c envs/dev.env.txt
599607
# pydantic
@@ -753,6 +761,11 @@ sphinx==8.1.3
753761
# myst-nb
754762
# myst-parser
755763
# pydata-sphinx-theme
764+
# sphinx-autobuild
765+
sphinx-autobuild==2024.10.3
766+
# via
767+
# -c envs/dev.env.txt
768+
# -r deps/docs.txt
756769
sphinxcontrib-applehelp==2.0.0
757770
# via
758771
# -c envs/dev.env.txt
@@ -785,6 +798,10 @@ stack-data==0.6.3
785798
# via
786799
# -c envs/dev.env.txt
787800
# ipython
801+
starlette==0.46.2
802+
# via
803+
# -c envs/dev.env.txt
804+
# sphinx-autobuild
788805
sympy==1.12.1
789806
# via
790807
# -c envs/dev.env.txt
@@ -882,6 +899,7 @@ typing-extensions==4.13.2
882899
# referencing
883900
# sqlalchemy
884901
# typing-inspection
902+
# uvicorn
885903
typing-inspection==0.4.0
886904
# via
887905
# -c envs/dev.env.txt
@@ -898,6 +916,14 @@ urllib3==2.4.0
898916
# via
899917
# -c envs/dev.env.txt
900918
# requests
919+
uvicorn==0.34.2
920+
# via
921+
# -c envs/dev.env.txt
922+
# sphinx-autobuild
923+
watchfiles==1.0.5
924+
# via
925+
# -c envs/dev.env.txt
926+
# sphinx-autobuild
901927
wcwidth==0.2.13
902928
# via
903929
# -c envs/dev.env.txt
@@ -915,6 +941,10 @@ websocket-client==1.8.0
915941
# via
916942
# -c envs/dev.env.txt
917943
# jupyter-server
944+
websockets==15.0.1
945+
# via
946+
# -c envs/dev.env.txt
947+
# sphinx-autobuild
918948
werkzeug==3.0.6
919949
# via
920950
# -c envs/dev.env.txt

‎docs/Makefile

+38-8
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,48 @@
1-
# Minimal makefile for Sphinx documentation
1+
# Copyright 2025 Google LLC
22
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# https://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
######## Configuration ########
316

4-
# You can set these variables from the command line, and also
5-
# from the environment for the first two.
6-
SPHINXOPTS ?=
7-
SPHINXBUILD ?= sphinx-build
8-
SOURCEDIR = .
9-
BUILDDIR = _build
17+
# Before we go any further, test if certain programs are available.
18+
PROGRAMS_NEEDED = sphinx-build sphinx-autobuild
19+
TEST := $(foreach p,$(PROGRAMS_NEEDED),\
20+
$(if $(shell which $(p)),_,$(error Cannot find program "$(p)")))
21+
22+
# The first two can be overridden via env vars.
23+
SPHINXOPTS ?=
24+
SPHINXBUILD ?= sphinx-build
25+
SPHINXAUTO = sphinx-autobuild
26+
SPHINXAUTOOPTS = --open-browser -j auto
27+
SOURCEDIR = .
28+
BUILDDIR = _build
29+
30+
.PHONY: help Makefile
31+
32+
######## Targets ########
1033

1134
# Put it first so that "make" without argument is like "make help".
1235
help:
1336
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
1437

15-
.PHONY: help Makefile
38+
auto autobuild live livehtml:
39+
@$(SPHINXAUTO) "$(SOURCEDIR)" "$(BUILDDIR)"/html $(SPHINXOPTS) $(SPHINXAUTOOPTS) $(O)
40+
41+
# The next one is for working on a theme, when it's best to disable incremental builds using "-a".
42+
# The build times are much slower, but CSS and template changes are picked up, and that's critical.
43+
# C.f. https://github.com/sphinx-doc/sphinx-autobuild#working-on-a-sphinx-html-theme
44+
auto-dev:
45+
@$(SPHINXAUTO) -a "$(SOURCEDIR)" "$(BUILDDIR)"/html $(SPHINXOPTS) $(SPHINXAUTOOPTS) $(O)
1646

1747
# Catch-all target: route all unknown targets to Sphinx using the new
1848
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).

‎docs/_static/fixes.css

+7-1
Original file line numberDiff line numberDiff line change
@@ -13,4 +13,10 @@ table.fixed.responsive {
1313
table.tfo-notebook-buttons.tfo-api {
1414
width: 100%;
1515
margin-bottom: 1.5em;
16-
}
16+
}
17+
18+
/* Adjust size of GitHub icon in the nav bar.
19+
*/
20+
html .pst-navbar-icon {
21+
font-size: 1.5rem;
22+
}

‎docs/_static/qai-theme.css

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
/* Copyright 2025 Google LLC
2+
*
3+
* Licensed under the Apache License, Version 2.0 (the "License");
4+
* you may not use this file except in compliance with the License.
5+
* You may obtain a copy of the License at
6+
*
7+
* https://www.apache.org/licenses/LICENSE-2.0
8+
*
9+
* Unless required by applicable law or agreed to in writing, software
10+
* distributed under the License is distributed on an "AS IS" BASIS,
11+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
* See the License for the specific language governing permissions and
13+
* limitations under the License.
14+
*/
15+
16+
:root {
17+
--qai-color-blue-500: #4285f4;
18+
--qai-color-blue-700: #1967d2;
19+
20+
--qai-color-magenta-400: #d367c4;
21+
--qai-color-magenta-500: #b356cd;
22+
--qai-color-magenta-700: #7c42c0;
23+
}
24+
25+
html[data-theme="light"] {
26+
/* The primary color is used as the unvisited link color. */
27+
--pst-color-primary: var(--qai-color-blue-700);
28+
--pst-color-secondary: var(--qai-color-blue-500);
29+
30+
/* Color inline code is for `backtick text`. */
31+
--pst-color-inline-code: var(--qai-color-magenta-700);
32+
--pst-color-inline-code-links: var(--qai-color-magenta-500);
33+
34+
/* Some code boxes have an accent color on the left border. */
35+
--mystnb-source-margin-color: var(--qai-color-magenta-700);
36+
}
37+
38+
a[data-theme=light]:hover {
39+
color: var(--qai-color-blue-700);
40+
}
41+
42+
43+
html[data-theme=dark] {
44+
/* The primary color is used as the unvisited link color. */
45+
--pst-color-primary: var(--qai-color-blue-500);
46+
--pst-color-secondary: var(--qai-color-blue-700);
47+
48+
/* Color inline code is for `backtick text`. */
49+
--pst-color-inline-code: var(--qai-color-magenta-400);
50+
--pst-color-inline-code-links: var(--qai-color-magenta-500);
51+
52+
/* Some code boxes have an accent color on the left border. */
53+
--mystnb-source-margin-color: var(--qai-color-magenta-700);
54+
}
55+
56+
a[data-theme=dark]:hover {
57+
color: var(--qai-color-blue-700);
58+
}

‎docs/_templates/qai_logo.html

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

‎docs/_templates/qualtran-sidebar.html

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{# Displays the TOC-subtree for pages nested under the currently active top-level TOCtree element. #}
2+
<nav class="bd-docs-nav bd-links"
3+
aria-label="{{ title }}">
4+
<p class="bd-links__title" role="heading" aria-level="1">{{ title }}</p>
5+
<div class="bd-toc-item navbar-nav">
6+
{{- generate_toctree_html(
7+
"sidebar",
8+
show_nav_level=theme_show_nav_level | int,
9+
maxdepth=theme_navigation_depth | int,
10+
collapse=theme_collapse_navigation | tobool,
11+
includehidden=theme_sidebar_includehidden | tobool,
12+
titles_only=True
13+
)
14+
-}}
15+
</div>
16+
</nav>

‎docs/conf.py

+28-2
Original file line numberDiff line numberDiff line change
@@ -47,10 +47,36 @@
4747
templates_path = ['_templates']
4848
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
4949

50-
5150
# -- Options for HTML output -------------------------------------------------
5251
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
5352

5453
html_theme = 'pydata_sphinx_theme'
54+
html_theme_options = {
55+
"navbar_start": ["navbar-logo"],
56+
"navbar_center": ["navbar-nav"],
57+
"navbar_end": ["navbar-icon-links", "theme-switcher"],
58+
"icon_links": [
59+
{
60+
"name": "GitHub repository",
61+
"url": "https://github.com/quantumlib/Qualtran",
62+
"icon": "fab fa-github-square",
63+
"type": "fontawesome",
64+
}
65+
],
66+
"footer_center": ["qai_logo"],
67+
}
68+
69+
# qualtran-sidebar.html replaces the default sidebar title 'Section navigation'
70+
# with the appropriate section title.
71+
html_sidebars = {
72+
"bloq_infra": ["qualtran-sidebar"],
73+
"bloqs/index": ["qualtran-sidebar"],
74+
"reference/index": ["qualtran-sidebar"],
75+
}
76+
5577
html_static_path = ['_static']
56-
html_css_files = ['fixes.css']
78+
html_css_files = ['fixes.css', 'qai-theme.css']
79+
html_logo = 'https://raw.githubusercontent.com/quantumlib/Qualtran/refs/heads/main/docs/_static/qualtran-logo-mode-sensitive.svg'
80+
html_favicon = (
81+
'https://raw.githubusercontent.com/quantumlib/Qualtran/refs/heads/main/docs/_static/favicon.png'
82+
)

0 commit comments

Comments
 (0)