From 2f02fc7f900bbe3847437dfdab239f2a0aeac763 Mon Sep 17 00:00:00 2001
From: spectrometerHBH <bohanhou@andrew.cmu.edu>
Date: Mon, 22 Jun 2026 00:07:39 -0400
Subject: [PATCH] [Docs] Switch documentation theme to sphinx-book-theme

- docs/conf.py: default html_theme -> sphinx-book-theme (book-theme options;
  tlcpack layout overrides scoped to the RTD theme); docs/_static/css/tirx_theme.css
  for the dark-mode logo backing.
- tests/scripts/task_python_docs.sh: install sphinx-book-theme==1.1.4 at docs-build
  time. It is already declared in docker/install/ubuntu_install_sphinx.sh, but the
  currently-published ci-gpu image predates that dependency, so install it in the
  docs job until the CI image is refreshed.

sphinx-book-theme 1.1.4 builds cleanly under Sphinx 8.1.3.
---
 docs/_static/css/tirx_theme.css   | 27 +++++++++++++++++++++++++
 docs/conf.py                      | 33 ++++++++++++++++++++++++-------
 tests/scripts/task_python_docs.sh |  5 +++++
 3 files changed, 58 insertions(+), 7 deletions(-)
 create mode 100644 docs/_static/css/tirx_theme.css

diff --git a/docs/_static/css/tirx_theme.css b/docs/_static/css/tirx_theme.css
new file mode 100644
index 000000000000..31afcf22bf78
--- /dev/null
+++ b/docs/_static/css/tirx_theme.css
@@ -0,0 +1,27 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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
+ *
+ *   http://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.
+ */
+
+/* The TVM brand logo is dark artwork on a transparent background, so in dark
+ * mode it disappears against the dark navbar/sidebar. Give it a white backing
+ * (dark mode only; light mode already shows it fine). */
+html[data-theme="dark"] img.logo__image {
+  background: #ffffff;
+  padding: 3px 6px;
+  border-radius: 5px;
+}
diff --git a/docs/conf.py b/docs/conf.py
index 9fa136c0b68c..c24ef23a92ab 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -354,7 +354,7 @@ def jupyter_notebook(script_blocks, gallery_conf, target_dir, real_func):
 # -- Options for HTML output ----------------------------------------------
 
 # The theme is set by the make target
-html_theme = os.environ.get("TVM_THEME", "rtd")
+html_theme = os.environ.get("TVM_THEME", "sphinx_book_theme")
 
 on_rtd = os.environ.get("READTHEDOCS", None) == "True"
 # only import rtd theme and set it if want to build docs locally
@@ -366,9 +366,25 @@ def jupyter_notebook(script_blocks, gallery_conf, target_dir, real_func):
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
-html_theme_options = {
-    "logo_only": True,
-}
+if html_theme == "sphinx_book_theme":
+    html_theme_options = {
+        "repository_url": "https://github.com/apache/tvm",
+        "repository_branch": "main",
+        "path_to_docs": "docs/",
+        "use_repository_button": True,
+        "use_issues_button": True,
+        "use_edit_page_button": False,
+        "home_page_in_toc": False,
+        "show_navbar_depth": 1,
+        "show_toc_level": 2,
+    }
+else:
+    html_theme_options = {
+        "logo_only": True,
+    }
+
+if html_theme == "sphinx_book_theme":
+    html_css_files = ["css/tirx_theme.css"]
 
 html_logo = "_static/img/tvm-logo-small.png"
 
@@ -561,9 +577,12 @@ def fixup_tutorials(original_url: str) -> str:
     "edit_link_hook_fn": fixup_tutorials,
 }
 
-# add additional overrides
-templates_path += [tlcpack_sphinx_addon.get_templates_path()]
-html_static_path += [tlcpack_sphinx_addon.get_static_path()]
+# add additional overrides. The tlcpack templates override layout.html for the
+# RTD theme (and assume its header/footer html_context); only apply them when the
+# RTD theme is active so they don't clobber another theme's own layout.
+if html_theme == "sphinx_rtd_theme":
+    templates_path += [tlcpack_sphinx_addon.get_templates_path()]
+    html_static_path += [tlcpack_sphinx_addon.get_static_path()]
 
 
 def update_alias_docstring(name, obj, lines):
diff --git a/tests/scripts/task_python_docs.sh b/tests/scripts/task_python_docs.sh
index 7c3122cd9233..29e94250a66d 100755
--- a/tests/scripts/task_python_docs.sh
+++ b/tests/scripts/task_python_docs.sh
@@ -26,6 +26,11 @@ export OMP_NUM_THREADS=1
 IS_LOCAL=${IS_LOCAL:-0}
 PYTHON_DOCS_ONLY=${PYTHON_DOCS_ONLY:-0}
 
+# sphinx-book-theme is declared in docker/install/ubuntu_install_sphinx.sh, but the
+# currently-published ci-gpu image predates that dependency. Install it here so the
+# docs build can use the book theme until the CI image is refreshed.
+uv pip install "sphinx-book-theme==1.1.4"
+
 cleanup()
 {
     rm -rf /tmp/$$.log.txt