docs: Add USB Host and Device Chinese documentation

tore-espressif · tore-espressif · commit 8a12a70a68ae · 2025-12-02T16:10:40.000+01:00
diff --git a/docs/build_docs.sh b/docs/build_docs.sh
@@ -1,4 +1,4 @@
 #!/bin/bash
 # SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
 #
-build-docs -l en --project-path .. -t esp32s2 esp32s3 esp32p4 esp32h4
+build-docs --project-path .. -t esp32s2 esp32s3 esp32p4 esp32h4
diff --git a/docs/conf_common.py b/docs/conf_common.py
@@ -14,13 +14,14 @@
                'esp_docs.esp_extensions.run_doxygen',
                ]
 # Languages supported
-languages = ['en']
+languages = ['en', 'zh_CN']
 
 # Project targets (used as URL slugs)
 idf_targets = ['esp32s2', 'esp32s3', 'esp32p4', 'esp32h4']
 
 # GitHub repository information
 github_repo = 'espressif/esp-usb'
+project_homepage = 'https://github.com/espressif/esp-usb'
 
 # Initialize html_context if not already defined
 html_context = {}
diff --git a/docs/en/usb_host/usb_host_notes_arch.rst b/docs/en/usb_host/usb_host_notes_arch.rst
@@ -1,8 +1,6 @@
 USB Host Maintainers Notes (Architecture)
 =========================================
 
-:link_to_translation:`zh_CN:[中文]`
-
 The Host Stack is roughly split into multiple layers of abstraction, with each layer representing different USB concepts and a different level of USB Host operation. For example, a higher layer may present an abstraction of devices and application data transfers, whereas a lower layer may present an abstraction of endpoints and USB transfers.
 
 Layer Descriptions
@@ -22,10 +20,10 @@ The layers of the Host Stack are described in the following table. The layers ar
       - This layer represents the USB Controller Hardware of the {IDF_TARGET_NAME}. The API presented by this layer is the register interface of the controller.
     * - LL
       - ``usbh_ll.h``
-      - The LL (Low Level) layer abstracts the basic register access of the USB controller according to ESP-IDF's :doc:`Hardware Abstraction API Guidelines <../../../api-guides/hardware-abstraction>`. In other words, this layer provides APIs to access the controller's registers and format/parse the controller's DMA descriptors.
+      - The LL (Low Level) layer abstracts the basic register access of the USB controller according to ESP-IDF's `Hardware Abstraction API Guidelines <https://docs.espressif.com/projects/esp-idf/en/stable/{IDF_TARGET_PATH_NAME}/api-guides/hardware-abstraction.html>`__. In other words, this layer provides APIs to access the controller's registers and format/parse the controller's DMA descriptors.
     * - HAL
       - ``usbh_hal.h``, ``usbh_hal.c``
-      - The HAL (Hardware Abstraction Layer) abstracts the operating steps of the USB controller into functions according to ESP-IDF's :doc:`Hardware Abstraction API Guidelines <../../../api-guides/hardware-abstraction>`. This layer also abstracts the controller's host port and host channels, and provides APIs to operate the them.
+      - The HAL (Hardware Abstraction Layer) abstracts the operating steps of the USB controller into functions according to ESP-IDF's `Hardware Abstraction API Guidelines <https://docs.espressif.com/projects/esp-idf/en/stable/{IDF_TARGET_PATH_NAME}/api-guides/hardware-abstraction.html>`__. This layer also abstracts the controller's host port and host channels, and provides APIs to operate the them.
     * - HCD
       - ``hcd.h``, ``hcd.c``
       - The HCD (Host Controller Driver) acts as hardware agnostic API for all USB controllers (i.e., an API that can theoretically be used with any USB controller implementation). This layer also abstracts the root port (i.e., root hub) and USB pipes.
@@ -39,7 +37,7 @@ The layers of the Host Stack are described in the following table. The layers ar
       - ``usb_host.h``, ``usb_host.c``
       - The USB Host Library layer is the lowest public API layer of the Host Stack and presents the concept of USB Host Clients. The abstraction of clients allows for multiple class drivers to coexist simultaneously (where each class roughly maps to a single client) and also acts as a mechanism for division of labor (where each client is responsible for its own processing and event handling).
     * - Host Class Drivers
-      - See the `ESP-USB repository <https://github.com/espressif/esp-usb>`_ or the USB Host examples in ESP-IDF (via :example:`peripherals/usb/host`).
+      - See the `ESP-USB repository <https://github.com/espressif/esp-usb>`_ or the USB Host examples in ESP-IDF.
       - The Host Class Drivers implement the host side of a particular device class (e.g., CDC, MSC, HID). The exposed API is specific to each class driver.
 
 Layer Dependencies
diff --git a/docs/en/usb_host/usb_host_notes_design.rst b/docs/en/usb_host/usb_host_notes_design.rst
@@ -1,8 +1,6 @@
 USB Host Maintainers Notes (Design Guidelines)
 ==============================================
 
-:link_to_translation:`zh_CN:[中文]`
-
 Design Considerations
 ---------------------
 
diff --git a/docs/en/usb_host/usb_host_notes_dwc_otg.rst b/docs/en/usb_host/usb_host_notes_dwc_otg.rst
@@ -1,8 +1,6 @@
 USB Host Maintainers Notes (DWC_OTG Controller)
 ===============================================
 
-:link_to_translation:`zh_CN:[中文]`
-
 The {IDF_TARGET_NAME} uses a DesignWare USB 2.0 On-the-Go Controller (henceforth referred to as DWC_OTG in this document) as its underlying hardware controller, where the DWC_OTG operates in Host Mode with Scatter/Gather DMA enabled.
 
 .. note::
diff --git a/docs/en/usb_host/usb_host_notes_index.rst b/docs/en/usb_host/usb_host_notes_index.rst
@@ -1,8 +1,6 @@
 USB Host Maintainers Notes (Introduction)
 =========================================
 
-:link_to_translation:`zh_CN:[中文]`
-
 This document contains information regarding the implementation details of the USB Host stack. This document is intended for the maintainers and third-party contributors of the USB Host stack. Users of the USB Host stack should refer to :doc:`../usb_host` instead.
 
 .. warning::
diff --git a/docs/zh_CN/conf.py b/docs/zh_CN/conf.py
@@ -0,0 +1,32 @@
+# SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Apache-2.0
+# -*- coding: utf-8 -*-
+#
+# Chinese Language RTD & Sphinx config file
+#
+# Uses ../conf_common.py for most non-language-specific settings.
+
+# Importing conf_common adds all the non-language-specific
+# parts to this conf module
+
+try:
+    from conf_common import *  # noqa: F403,F401
+except ImportError:
+    import os
+    import sys
+    sys.path.insert(0, os.path.abspath('../'))
+    from conf_common import *  # noqa: F403,F401
+
+import datetime
+
+current_year = datetime.datetime.now().year
+
+# General information about the project.
+project = u'ESP-USB 编程指南'
+copyright = '2025 - {}, 乐鑫信息科技（上海）股份有限公司'.format(current_year)  # noqa: A001
+author = u'乐鑫信息科技（上海）股份有限公司'
+pdf_title = u'ESP-USB 编程指南'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+language = 'zh_CN'
diff --git a/docs/zh_CN/index.rst b/docs/zh_CN/index.rst
@@ -0,0 +1,20 @@
+.. SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+..
+.. SPDX-License-Identifier: Apache-2.0
+
+ESP-USB Programming Guide
+==========================
+
+Welcome to the ESP-USB Programming Guide.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   introduction
+
+.. toctree::
+   :maxdepth: 1
+
+   usb_host
+   usb_device
diff --git a/docs/zh_CN/introduction.rst b/docs/zh_CN/introduction.rst
@@ -0,0 +1,17 @@
+.. SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+..
+.. SPDX-License-Identifier: Apache-2.0
+
+Introduction
+============
+
+ESP-USB is a repository containing ESP-IDF USB host and device class drivers
+which have been separated and uploaded into IDF Component Manager.
+
+This documentation will be expanded with detailed information about:
+
+* USB Host Library
+* USB Device Drivers
+* USB Class Drivers (CDC, HID, MSC, UAC, UVC)
+* API Reference
+* Examples and Usage
diff --git a/docs/zh_CN/usb_device.rst b/docs/zh_CN/usb_device.rst
diff --git a/docs/zh_CN/usb_host.rst b/docs/zh_CN/usb_host.rst

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`	`1`	`#!/bin/bash`
`2`	`2`	`# SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD`
`3`	`3`	`#`
`4`		`-build-docs -l en --project-path .. -t esp32s2 esp32s3 esp32p4 esp32h4`
	`4`	`+build-docs --project-path .. -t esp32s2 esp32s3 esp32p4 esp32h4`