From 7e90c920b3b4742e33f15e2f604a1522c3dc93f1 Mon Sep 17 00:00:00 2001
From: sansiro77 <30891481+sansiro77@users.noreply.github.com>
Date: Wed, 13 May 2026 13:32:21 +0800
Subject: [PATCH] Update Sphinx theme integration

---
 docs/source/conf.py   | 46 ++++++++++++++++++++++++++++++++++++++++++-
 pyproject.toml        |  2 +-
 requirements-docs.txt |  2 +-
 3 files changed, 47 insertions(+), 3 deletions(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 7c3aeb4c..4ca1a8f8 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -6,6 +6,7 @@
 import os
 import shutil
 import sys
+from copy import deepcopy
 
 import deepquantum as dq
 
@@ -62,11 +63,37 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'sphinx_book_theme'
+html_theme = 'turingq_sphinx_theme'
 html_static_path = ['_static']
 html_title = f'{project} v{release}'
+html_context = {'default_mode': 'light'}
+
+_TURINGQ_HOME_URL = 'index.html'
+_TURINGQ_NAV = [
+    {'text': '首页', 'url': _TURINGQ_HOME_URL, 'external': False},
+    {
+        'text': '使用教程',
+        'children': [
+            {'text': '使用教程', 'url': 'https://dqapi.turingq.com', 'external': True},
+            {'text': '安装', 'url': 'https://github.com/TuringQ/deepquantum', 'external': True},
+        ],
+    },
+    {
+        'text': '算法案例',
+        'url': 'https://deepquantum.turingq.com/deep-quantum-case',
+        'external': True,
+    },
+    {
+        'text': '赛事活动',
+        'url': 'https://deepquantum.turingq.com/competition/',
+        'external': True,
+    },
+]
 
 html_theme_options = {
+    'turingq_company_chrome': True,  # 启用 TuringQ 公司页眉、页脚和主题附加资源
+    'turingq_logo_href': _TURINGQ_HOME_URL,
+    'turingq_nav': _TURINGQ_NAV,
     # 启用右侧的“在 GitHub 上编辑/查看”按钮
     'repository_url': 'https://github.com/TuringQ/deepquantum',
     'use_repository_button': True,  # 开启 GitHub 仓库链接
@@ -79,6 +106,22 @@
 }
 
 
+def _home_href(app, pagename):
+    """Return a page-relative link to the documentation home page."""
+    if pagename == 'index':
+        return _TURINGQ_HOME_URL
+    return app.builder.get_relative_uri(pagename, 'index')
+
+
+def _resolve_home_links(app, pagename, templatename, context, doctree):  # noqa: ARG001
+    """Keep TuringQ chrome home links working under nested Read the Docs paths."""
+    home_href = _home_href(app, pagename)
+    nav = deepcopy(_TURINGQ_NAV)
+    nav[0]['url'] = home_href
+    context['theme_turingq_logo_href'] = home_href
+    context['theme_turingq_nav'] = nav
+
+
 def _copy_demos_fig_folders(app, exception):
     """Copy 'images' directories from subfolders in 'docs/source/demos' to the HTML build directory."""
     if exception:
@@ -98,4 +141,5 @@ def _copy_demos_fig_folders(app, exception):
 
 
 def setup(app):
+    app.connect('html-page-context', _resolve_home_links)
     app.connect('build-finished', _copy_demos_fig_folders)
diff --git a/pyproject.toml b/pyproject.toml
index 5ad47c29..28f93849 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -64,7 +64,7 @@ dev = [
 docs = [
     'myst-nb',
     'sphinx',
-    'sphinx_book_theme',
+    'turingq-sphinx-theme',
 ]
 
 [project.urls]
diff --git a/requirements-docs.txt b/requirements-docs.txt
index 30f473f4..b063fbe1 100644
--- a/requirements-docs.txt
+++ b/requirements-docs.txt
@@ -1,3 +1,3 @@
 myst-nb
 sphinx
-sphinx_book_theme
+turingq-sphinx-theme