From ac4cd16cdf69cda79303f9b020ea89e478067d9c Mon Sep 17 00:00:00 2001
From: luweike <luweike@espressif.com>
Date: Tue, 14 Oct 2025 16:14:23 +0800
Subject: [PATCH] docs: Add intro and brief descriptions to Bluetooth Common
 API home page

---
 docs/en/api-reference/bluetooth/bt_common.rst | 32 +++++++++++++++--
 .../api-reference/bluetooth/bt_common.rst     | 36 ++++++++++++++++++-
 2 files changed, 64 insertions(+), 4 deletions(-)

diff --git a/docs/en/api-reference/bluetooth/bt_common.rst b/docs/en/api-reference/bluetooth/bt_common.rst
index 460bf23c07..02acae01c9 100644
--- a/docs/en/api-reference/bluetooth/bt_common.rst
+++ b/docs/en/api-reference/bluetooth/bt_common.rst
@@ -1,9 +1,35 @@
-Bluetooth® Common
-=================
+Bluetooth\ :sup:`®` Common
+===============================
+
+:link_to_translation:`zh_CN:[中文]`
+
+**Bluetooth Common** provides shared definitions and APIs used by both Bluetooth Classic and Bluetooth Low Energy (Bluetooth LE). It serves as a foundation for shared functionality across Bluetooth components, offering unified interfaces for Bluetooth initialization, configuration, and device management.
+
+The Bluetooth Common API is organized into the following parts:
 
 .. toctree::
-   :caption: Bluetooth Common Defines and APIs
+   :maxdepth: 1
 
    Bluetooth Define <esp_bt_defs>
+
+Provides shared definitions and data structures used by both Bluetooth Classic and Bluetooth LE.
+
+.. toctree::
+   :maxdepth: 1
+
    Bluetooth Main <esp_bt_main>
+
+Provides core APIs for initializing, enabling/disabling, and managing the Bluetooth stack.
+
+.. toctree::
+   :maxdepth: 1
+
    Bluetooth Device <esp_bt_device>
+
+Provides APIs for managing device-level properties such as address, name, visibility, and coexistence settings.
+
+Each part typically includes the following sections:
+
+- **Overview**: Summary of purpose, key functionality, and main interfaces
+- **Application Examples**: Example projects demonstrating typical usage
+- **API Reference**: Detailed API documentation, including header files, functions, structures, macros, type definitions, and enumerations
diff --git a/docs/zh_CN/api-reference/bluetooth/bt_common.rst b/docs/zh_CN/api-reference/bluetooth/bt_common.rst
index 4bf3fbfd92..eebea1e42d 100644
--- a/docs/zh_CN/api-reference/bluetooth/bt_common.rst
+++ b/docs/zh_CN/api-reference/bluetooth/bt_common.rst
@@ -1 +1,35 @@
-.. include:: ../../../en/api-reference/bluetooth/bt_common.rst
+蓝牙\ :sup:`®` 通用 API
+=========================
+
+:link_to_translation:`en:[English]`
+
+**蓝牙通用 API** 提供经典蓝牙和低功耗蓝牙共用的定义和 API。它为各蓝牙组件提供基础功能，提供统一的接口用于蓝牙初始化、配置和设备管理。
+
+蓝牙通用 API 包含以下部分：
+
+.. toctree::
+   :maxdepth: 1
+
+   Bluetooth Define <esp_bt_defs>
+
+提供经典蓝牙和低功耗蓝牙共用的定义和数据结构。
+
+.. toctree::
+   :maxdepth: 1
+
+   Bluetooth Main <esp_bt_main>
+
+提供核心 API，用于初始化、启用/禁用和管理蓝牙主机栈。
+
+.. toctree::
+   :maxdepth: 1
+
+   Bluetooth Device <esp_bt_device>
+
+提供设备级 API，用于管理设备属性，例如地址、名称、可见性和共存设置。
+
+每个部分通常包含以下内容：
+
+- **概述**： 主要用途、核心功能和关键接口
+- **应用示例**：展示典型使用场景的示例
+- **API 参考**：详细 API 文档，包括头文件、函数、结构体、宏、类型定义和枚举