更新doc文档中心配置

docs/source/_static/language_switch.css

@@ -52,12 +52,23 @@
     user-select: none;
 }
 
-/* 语言切换容器样式 - 使用深灰色背景 */
-.language-switch-container {
-    position: absolute;
-    bottom: 0;
-    left: 0;
-    right: 0;
+/* 侧边栏采用flex布局：上部滚动目录 + 底部固定语言切换 */
+.wy-nav-side {
+    display: flex;
+    flex-direction: column;
+    height: 100vh;
+    min-height: 0; /* 允许子元素正确缩放 */
+}
+
+.wy-side-scroll {
+    flex: 1 1 auto;
+    min-height: 0; /* 关键：使滚动区域在flex容器内可滚动 */
+    overflow-y: auto;
+    -webkit-overflow-scrolling: touch;
+}
+
+.wy-nav-side .language-switch-container {
+    flex: 0 0 36px;
     background: #1a1a1a; /* 深灰色背景替代蓝色 */
     border-top: 1px solid rgba(255, 255, 255, 0.05);
     z-index: 20;
@@ -83,7 +94,7 @@
         min-width: 40px;
     }
 
-    .language-switch-container {
+    .wy-nav-side .language-switch-container {
         height: 32px; /* 移动端更小的高度 */
     }
 }

docs/source/_static/language_switch.js

@@ -48,8 +48,8 @@
             return;
         }
 
-        // 查找侧边栏容器
-        const sidebar = document.querySelector('.wy-nav-side .wy-side-scroll');
+        // 查找侧边栏容器（使用 .wy-nav-side，确保位于侧栏根部而非滚动容器内）
+        const sidebar = document.querySelector('.wy-nav-side');
         if (!sidebar) {
             console.warn('未找到侧边栏容器');
             return;
@@ -72,7 +72,7 @@
             </div>
         `;
 
-        // 将语言切换器添加到侧边栏底部
+        // 将语言切换器添加到侧边栏底部（作为 .wy-nav-side 的直接子元素）
         sidebar.insertAdjacentHTML('beforeend', languageSwitchHTML);
         console.log('语言切换器已动态创建');
     }
@@ -258,6 +258,13 @@
      * 初始化语言切换器
      */
     function initLanguageSwitch() {
+        // 如果模板已经渲染在 .wy-side-scroll 内部，则搬移到 .wy-nav-side 下
+        const existingContainer = document.querySelector('.wy-side-scroll > .language-switch-container');
+        const sideRoot = document.querySelector('.wy-nav-side');
+        if (existingContainer && sideRoot) {
+            sideRoot.appendChild(existingContainer);
+        }
+
         createLanguageSwitch();
         setupLanguageSwitchEvents();
         updateNavigationLanguage();

docs/source/_static/version_menu.js

@@ -9,23 +9,6 @@
     };
 
     // 从版本配置文件获取版本信息
-    // 获取嵌入的版本配置（在构建时由脚本生成）
-    function getEmbeddedVersionConfig() {
-        return {
-  "versions": [
-    {
-      "name": "master",
-      "display_name": "latest",
-      "branch": "main",
-      "url_path": "latest",
-      "description": "最新开发版本"
-    }
-  ],
-  "default_version": "master",
-  "latest_version": "master"
-};
-    }
-
     async function fetchVersionInfo() {
         try {
             // 智能检测当前版本

docs/source/_templates/globaltoc.html

@@ -10,17 +10,4 @@ <h3><a href="{{ pathto(master_doc) }}">{{ _('Table of Contents') }}</a></h3>
   {{ toctree(maxdepth=navigation_depth, collapse=False, includehidden=True, titles_only=False) }}
 </div>
 
-{# 中英文切换UI - 位于多级目录下方，作为独立的区域 #}
-<div class="language-switch-container">
-  <div class="language-switch" id="language-switch">
-    <div class="language-switch__container">
-      <button class="language-switch__option" data-lang="chinese" aria-label="切换到中文">
-        中文
-      </button>
-      <span class="language-switch__separator">|</span>
-      <button class="language-switch__option" data-lang="english" aria-label="Switch to English">
-        English
-      </button>
-    </div>
-  </div>
-</div>
+{# 语言切换UI 由 language_switch.js 注入至 .wy-nav-side 底部 #}

docs/source/_templates/layout.html

@@ -26,6 +26,32 @@
   </script>
 {% endblock %}
 
+{# 将 giscus 插入到正文（内容）块的末尾，紧跟文章内容之后 #}
+{% block content %}
+  {{ super() }}
+  {% if giscus and giscus.get('enabled') and giscus.get('repo') and giscus.get('repo_id') and (giscus.get('category_id') or giscus.get('category')) %}
+    <div id="giscus_thread" class="giscus" style="margin: 2rem 0;"></div>
+    <script src="https://giscus.app/client.js"
+            data-repo="{{ giscus.get('repo') }}"
+            data-repo-id="{{ giscus.get('repo_id') }}"
+            {% if giscus.get('category_id') %}
+            data-category-id="{{ giscus.get('category_id') }}"
+            {% elif giscus.get('category') %}
+            data-category="{{ giscus.get('category') }}"
+            {% endif %}
+            data-mapping="{{ giscus.get('mapping', 'pathname') }}"
+            data-strict="{{ giscus.get('strict', 0) }}"
+            data-reactions-enabled="{{ giscus.get('reactions_enabled', 1) }}"
+            data-emit-metadata="{{ giscus.get('emit_metadata', 0) }}"
+            data-input-position="{{ giscus.get('input_position', 'bottom') }}"
+            data-theme="{{ giscus.get('theme', 'preferred_color_scheme') }}"
+            data-lang="{{ giscus.get('lang', 'zh-CN') }}"
+            {% if giscus.get('lazy') %} data-loading="lazy"{% endif %}
+            crossorigin="anonymous"
+            async>
+    </script>
+  {% endif %}
+{% endblock %}
 
 {% block extrahead %}
   {{ super() }}

docs/source/conf.py

@@ -28,6 +28,7 @@ def load_config():
 project_config = config.get('project', {})
 sphinx_config = config.get('sphinx', {})
 repository_config = config.get('repository', {})
+giscus_config = config.get('giscus', {})
 
 # -- Project information -----------------------------------------------------
 
@@ -234,6 +235,8 @@ def derive_edit_base_url():
 
 html_context = {
     'edit_base_url': derive_edit_base_url(),
+    # 将 giscus 配置传入模板；若未启用或缺关键字段，模板中将忽略
+    'giscus': giscus_config or {},
 }
 """
 LaTeX / PDF 构建配置

docs/source/config.yaml

@@ -70,7 +70,7 @@ categories:
     description: "常见问题解答"
     patterns:
       - "FAQ_page"
-      - "拓展外设配置指南"
+      - "FAQ_page/拓展外设配置指南"
 # 文档生成配置
 generation:
   copy_files: