From cff50edf83c464ae379b1d4a758a7d99fe3f8084 Mon Sep 17 00:00:00 2001 From: Michael Hucka Date: Tue, 29 Apr 2025 15:05:05 -0700 Subject: [PATCH 1/9] Add a set of definitions for the Qualtran colors --- docs/_static/qai-theme.css | 58 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 docs/_static/qai-theme.css diff --git a/docs/_static/qai-theme.css b/docs/_static/qai-theme.css new file mode 100644 index 000000000..18f5ce377 --- /dev/null +++ b/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); +} From 851e0715ecec09c1ab14ddd6466a3d79e73eda89 Mon Sep 17 00:00:00 2001 From: Michael Hucka Date: Tue, 29 Apr 2025 15:07:20 -0700 Subject: [PATCH 2/9] Add templates for PyData theme enhancements These are referenced in [`../conf.py`](../conf.py) to make adjustments to the Sphinx theme. --- docs/_templates/qai_logo.html | 4 ++++ docs/_templates/qualtran-sidebar.html | 16 ++++++++++++++++ 2 files changed, 20 insertions(+) create mode 100644 docs/_templates/qai_logo.html create mode 100644 docs/_templates/qualtran-sidebar.html diff --git a/docs/_templates/qai_logo.html b/docs/_templates/qai_logo.html new file mode 100644 index 000000000..40b0c5366 --- /dev/null +++ b/docs/_templates/qai_logo.html @@ -0,0 +1,4 @@ + + Google Quantum AI + diff --git a/docs/_templates/qualtran-sidebar.html b/docs/_templates/qualtran-sidebar.html new file mode 100644 index 000000000..e94b247c4 --- /dev/null +++ b/docs/_templates/qualtran-sidebar.html @@ -0,0 +1,16 @@ +{# Displays the TOC-subtree for pages nested under the currently active top-level TOCtree element. #} + From f845337ce61ebcb674009b12890f92033a0c5343 Mon Sep 17 00:00:00 2001 From: Michael Hucka Date: Tue, 29 Apr 2025 15:07:42 -0700 Subject: [PATCH 3/9] Adjust the size of the GitHub icon in the nav bar --- docs/_static/fixes.css | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/_static/fixes.css b/docs/_static/fixes.css index 440b01edb..f6c29fa56 100644 --- a/docs/_static/fixes.css +++ b/docs/_static/fixes.css @@ -13,4 +13,10 @@ table.fixed.responsive { table.tfo-notebook-buttons.tfo-api { width: 100%; margin-bottom: 1.5em; -} \ No newline at end of file +} + +/* Adjust size of GitHub icon in the nav bar. + */ +html .pst-navbar-icon { + font-size: 1.5rem; +} From 293a94bd12b4dd2b1ca8e670fb18d8d1e598d9a8 Mon Sep 17 00:00:00 2001 From: Michael Hucka Date: Tue, 29 Apr 2025 15:08:09 -0700 Subject: [PATCH 4/9] Configure changes to the Sphinx theme for Qualtran --- docs/conf.py | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index f80e11ee1..dcca3a8c8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -47,10 +47,34 @@ 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/8fa2e8ae4fa071ece632fb7a7f615918128983e3/docs/_static/qualtran-logo-mode-sensitive.svg' +html_favicon = 'https://raw.githubusercontent.com/quantumlib/Qualtran/refs/heads/main/docs/_static/favicon.png' From 30b1c994560fdf6811faff6674426f69a80cdbe0 Mon Sep 17 00:00:00 2001 From: Michael Hucka Date: Tue, 29 Apr 2025 15:09:11 -0700 Subject: [PATCH 5/9] Add more features to Makefile This adds: - Google copyright - sphinx-autobuild command --- docs/Makefile | 46 ++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 38 insertions(+), 8 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index d4bb2cbb9..4e92d9f14 100644 --- a/docs/Makefile +++ b/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). From 7f09a27fb1a33a6070bf9c62fd8183b32c88f48d Mon Sep 17 00:00:00 2001 From: Michael Hucka Date: Tue, 29 Apr 2025 15:10:29 -0700 Subject: [PATCH 6/9] Add sphinx-autobuild and update tensorflow-docs I couldn't get things to work without updating tensorflow-docs. Also, this adds sphinx-autobuild for use in docs/Makefile. --- dev_tools/requirements/deps/docs.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/dev_tools/requirements/deps/docs.txt b/dev_tools/requirements/deps/docs.txt index a83bd1793..58ca603cd 100644 --- a/dev_tools/requirements/deps/docs.txt +++ b/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 \ No newline at end of file +tensorflow-docs~=2023.5.24 From 522a3f8082b743db57b698e3ffc803cf4d718a53 Mon Sep 17 00:00:00 2001 From: mhucka Date: Tue, 29 Apr 2025 22:28:06 +0000 Subject: [PATCH 7/9] Update docs.env.txt for changes in docs requirements --- dev_tools/requirements/envs/docs.env.txt | 54 ++++++++++++++++++------ 1 file changed, 42 insertions(+), 12 deletions(-) diff --git a/dev_tools/requirements/envs/docs.env.txt b/dev_tools/requirements/envs/docs.env.txt index fff251761..e6d164f3f 100644 --- a/dev_tools/requirements/envs/docs.env.txt +++ b/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 From a05abc5f1021cb32b87039c7cd2fc04c39fb2516 Mon Sep 17 00:00:00 2001 From: Michael Hucka Date: Tue, 29 Apr 2025 18:18:46 -0700 Subject: [PATCH 8/9] Fix formatting according to black --- docs/conf.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index dcca3a8c8..8e24c2631 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -77,4 +77,6 @@ html_static_path = ['_static'] html_css_files = ['fixes.css', 'qai-theme.css'] html_logo = 'https://raw.githubusercontent.com/quantumlib/Qualtran/8fa2e8ae4fa071ece632fb7a7f615918128983e3/docs/_static/qualtran-logo-mode-sensitive.svg' -html_favicon = 'https://raw.githubusercontent.com/quantumlib/Qualtran/refs/heads/main/docs/_static/favicon.png' +html_favicon = ( + 'https://raw.githubusercontent.com/quantumlib/Qualtran/refs/heads/main/docs/_static/favicon.png' +) From aeed575f36fb40f8e081720ba06b0773c5fffcb2 Mon Sep 17 00:00:00 2001 From: Michael Hucka Date: Wed, 30 Apr 2025 13:21:01 -0700 Subject: [PATCH 9/9] Reference the current version of the logo qualtran file --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 8e24c2631..1848d49de 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -76,7 +76,7 @@ html_static_path = ['_static'] html_css_files = ['fixes.css', 'qai-theme.css'] -html_logo = 'https://raw.githubusercontent.com/quantumlib/Qualtran/8fa2e8ae4fa071ece632fb7a7f615918128983e3/docs/_static/qualtran-logo-mode-sensitive.svg' +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' )