Merge branch 'docs/soc_capability_tags' into 'master'

docs(ESPAT-2061): Enabled soc capability tags for target-specific doc builds

See merge request application/esp-at!2051

Author: xcguang

.gitlab/ci/build_docs.yml

@@ -1,8 +1,15 @@
+.build_docs_script: &build_docs_script
+  - cd docs
+  - ./check_lang_folder_sync.sh
+  - ./check_doc_chars.py
+  - pip install -r requirements.txt
+  - build-docs -t $DOCTGT -bs $DOC_BUILDERS -l $DOCLANG build
+
 .build_docs_template:
   extends:
     - .rules:build:build_doc
   stage: build
-  image: $CI_DOCKER_REGISTRY/esp-idf-doc-env-v5.4:1-1
+  image: $IDF_IMAGE
   needs: []
   tags:
     - build_docs
@@ -13,25 +20,37 @@
       - docs/_build/*/*/latex/*
       - docs/_build/*/*/html/*
     expire_in: 6 mos
+  before_script:
+    # esp-at-doc-env images ship esp-idf at /opt/esp/idf. GitLab does not run
+    # the image entrypoint, so export IDF_PATH + toolchain here.
+    - . /opt/esp/idf/export.sh
   script:
-    - cd docs
-    - ./check_lang_folder_sync.sh
-    - ./check_doc_chars.py
-    - pip install -r requirements.txt
-    - build-docs -t $DOCTGT -bs $DOC_BUILDERS -l $DOCLANG build
-  parallel:
-    matrix:
-      - DOCLANG: ["en", "zh_CN"]
-        DOCTGT: ["esp32", "esp32c2", "esp32c3", "esp32c5", "esp32c6", "esp32c61", "esp32s2"]
+    - *build_docs_script
 
 build_docs_html:
   extends:
     - .build_docs_template
   variables:
     DOC_BUILDERS: "html"
+  parallel:
+    matrix:
+      - DOCLANG: ["en", "zh_CN"]
+        DOCTGT: ["esp32", "esp32c2", "esp32c3", "esp32c6", "esp32s2"]
+        IDF_IMAGE: $CI_REGISTRY/ci/images/esp-at-doc-env-v5.4:1
+      - DOCLANG: ["en", "zh_CN"]
+        DOCTGT: ["esp32c5", "esp32c61"]
+        IDF_IMAGE: $CI_REGISTRY/ci/images/esp-at-doc-env-v5.5:1
 
 build_docs_pdf:
   extends:
     - .build_docs_template
   variables:
     DOC_BUILDERS: "latex"
+  parallel:
+    matrix:
+      - DOCLANG: ["en", "zh_CN"]
+        DOCTGT: ["esp32", "esp32c2", "esp32c3", "esp32c6", "esp32s2"]
+        IDF_IMAGE: $CI_REGISTRY/ci/images/esp-at-doc-env-v5.4:1
+      - DOCLANG: ["en", "zh_CN"]
+        DOCTGT: ["esp32c5", "esp32c61"]
+        IDF_IMAGE: $CI_REGISTRY/ci/images/esp-at-doc-env-v5.5:1

docs/at_extensions/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Apache-2.0

docs/at_extensions/idf_build_system.py

@@ -0,0 +1,91 @@
+# SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Apache-2.0
+
+import json
+import os
+import shutil
+import subprocess
+
+from esp_docs.idf_extensions.build_system import project_path as dummy_project_path
+
+from at_extensions.idf_env import get_idf_python, prepare_idf_env
+
+
+class AtIdfBuilder:
+    def __init__(self) -> None:
+        self.project_description = {}
+
+    def _run_idf_py(self, idf_py, args, cmake_build_dir):
+        result = subprocess.run(idf_py + args, env=os.environ.copy(), text=True, capture_output=True)
+        if result.returncode == 0:
+            return
+
+        details = '\n'.join(part for part in [result.stdout, result.stderr] if part and part.strip()).strip()
+        target = args[-1] if 'set-target' in args else 'unknown'
+        raise RuntimeError(
+            'Dummy ESP-IDF project setup failed for target {} (exit code {}).\n'
+            'Install tools with: python $IDF_PATH/tools/idf_tools.py install\n'
+            '{}'
+            .format(target, result.returncode, details)
+        )
+
+    def generate_idf_info(self, app, config):
+        os.environ['IDF_DOC_BUILD'] = 'y'
+
+        if not app.config.idf_target:
+            raise RuntimeError(
+                'A valid target is needed to build ESP-AT docs. '
+                'Please re-run build-docs with a target specified, e.g: build-docs -t esp32'
+            )
+
+        build_dir = os.path.dirname(app.doctreedir.rstrip(os.sep))
+        cmake_build_dir = os.path.join(build_dir, 'build_dummy_project')
+        idf_path = prepare_idf_env()
+        idf_py = [
+            get_idf_python(),
+            os.path.join(idf_path, 'tools', 'idf.py'),
+            '-B',
+            cmake_build_dir,
+            '-C',
+            dummy_project_path,
+            '-D',
+            'SDKCONFIG={}'.format(os.path.join(build_dir, 'dummy_project_sdkconfig')),
+        ]
+
+        shutil.rmtree(cmake_build_dir, ignore_errors=True)
+        print('Starting dummy IDF project for ESP-AT docs (IDF_PATH={})...'.format(idf_path))
+        self._run_idf_py(idf_py, ['--preview', 'set-target', app.config.idf_target], cmake_build_dir)
+        self._run_idf_py(idf_py, ['reconfigure'], cmake_build_dir)
+
+        with open(os.path.join(cmake_build_dir, 'project_description.json')) as f:
+            self.project_description = json.load(f)
+
+        if self.project_description['target'] != app.config.idf_target:
+            raise RuntimeError(
+                'Dummy IDF project target mismatch: expected {}, got {}.'
+                .format(app.config.idf_target, self.project_description['target'])
+            )
+
+        app.emit('project-build-info', self.project_description)
+        return []
+
+
+at_idf_builder = AtIdfBuilder()
+
+
+def setup(app):
+    try:
+        build_dir = os.environ['BUILDDIR']
+    except KeyError:
+        build_dir = os.path.dirname(app.doctreedir.rstrip(os.sep))
+
+    for directory in (build_dir, os.path.join(build_dir, 'inc')):
+        try:
+            os.mkdir(directory)
+        except OSError:
+            pass
+
+    app.add_event('project-build-info')
+    app.connect('config-inited', at_idf_builder.generate_idf_info)
+
+    return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'}

docs/at_extensions/idf_env.py

@@ -0,0 +1,79 @@
+# SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Apache-2.0
+
+import os
+import subprocess
+import sys
+
+_DOCS_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+_AT_ROOT = os.path.abspath(os.path.join(_DOCS_DIR, '..'))
+_PREPARED = False
+
+
+def _valid_idf_path(path):
+    return path and os.path.isfile(os.path.join(path, 'tools', 'idf.py'))
+
+
+def resolve_idf_path():
+    env_idf_path = os.environ.get('IDF_PATH')
+    if _valid_idf_path(env_idf_path):
+        return os.path.realpath(env_idf_path)
+
+    for candidate in (os.path.join(_AT_ROOT, 'esp-idf'), '/opt/esp/idf'):
+        if _valid_idf_path(candidate):
+            return os.path.realpath(candidate)
+
+    raise RuntimeError(
+        'Cannot find ESP-IDF for documentation build. '
+        'Set IDF_PATH, use an image that ships esp-idf at /opt/esp/idf, or clone esp-idf into esp-at/esp-idf.'
+    )
+
+
+def export_idf_tools(idf_root):
+    export_cmd = [
+        sys.executable,
+        os.path.join(idf_root, 'tools', 'idf_tools.py'),
+        '--non-interactive',
+        'export',
+        '--format=key-value',
+    ]
+    try:
+        output = subprocess.check_output(export_cmd, stderr=subprocess.STDOUT, text=True)
+    except subprocess.CalledProcessError as exc:
+        raise RuntimeError(
+            'Failed to export ESP-IDF build tools from {}.\n'
+            'Install the required tools first:\n'
+            '  python {}/tools/idf_tools.py install\n'
+            'Command output:\n{}'
+            .format(idf_root, idf_root, exc.output)
+        ) from exc
+
+    for line in output.splitlines():
+        if not line or '=' not in line:
+            continue
+        key, value = line.split('=', 1)
+        if key == 'PATH':
+            os.environ['PATH'] = value + os.pathsep + os.environ.get('PATH', '')
+        else:
+            os.environ[key] = value
+
+
+def get_idf_python():
+    idf_python_env = os.environ.get('IDF_PYTHON_ENV_PATH')
+    if idf_python_env:
+        idf_python = os.path.join(idf_python_env, 'bin', 'python')
+        if os.path.isfile(idf_python):
+            return idf_python
+    return sys.executable
+
+
+def prepare_idf_env():
+    global _PREPARED
+    if _PREPARED:
+        return os.environ['IDF_PATH']
+
+    idf_root = resolve_idf_path()
+    os.environ['IDF_PATH'] = idf_root
+    export_idf_tools(idf_root)
+    _PREPARED = True
+    return idf_root

docs/conf_common.py

@@ -6,7 +6,17 @@
 
 from __future__ import print_function, unicode_literals
 
+import os
 import os.path
+import subprocess
+import sys
+
+docs_dir = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, docs_dir)
+
+from at_extensions.idf_env import prepare_idf_env  # noqa: E402
+
+prepare_idf_env()
 
 #ESP_DOCS_PATH = os.environ['ESP_DOCS_PATH']
 
@@ -56,22 +66,24 @@
 
 ESP32S2_DOCS = []
 
-# format: {tag needed to include: documents to included}, tags are parsed from sdkconfig and peripheral_caps.h headers
+# format: {tag needed to include: documents to include}
+# Tags are chip names passed by build-docs -t <target> (e.g. esp32, esp32c3).
 conditional_include_dict = {
-                            'esp32':ESP32_DOCS,
-                            'esp32c2':ESP32C2_DOCS,
-                            'esp32c3':ESP32C3_DOCS,
-                            'esp32c5':ESP32C5_DOCS,
-                            'esp32c6':ESP32C6_DOCS,
-                            'esp32c61':ESP32C61_DOCS,
-                            'esp32s2':ESP32S2_DOCS
+                            'esp32': ESP32_DOCS,
+                            'esp32c2': ESP32C2_DOCS,
+                            'esp32c3': ESP32C3_DOCS,
+                            'esp32c5': ESP32C5_DOCS,
+                            'esp32c6': ESP32C6_DOCS,
+                            'esp32c61': ESP32C61_DOCS,
+                            'esp32s2': ESP32S2_DOCS,
                             }
 
 extensions += ['sphinx_copybutton',
                # Note: order is important here, events must
                # be registered by one extension before they can be
                # connected to another extension
-               'esp_docs.esp_extensions.dummy_build_system',
+               'at_extensions.idf_build_system',
+               'esp_docs.idf_extensions.gen_defines',
                'esp_docs.esp_extensions.run_doxygen',
                ]
 

docs/requirements.txt

@@ -1 +1 @@
-esp-docs==2.1.0
+esp-docs==2.5.1