docs: update git clone command to only clone latest commit

.gitmodules

@@ -26,6 +26,7 @@
 [submodule "components/bt/controller/lib_esp32"]
 	path = components/bt/controller/lib_esp32
 	url = ../../espressif/esp32-bt-lib.git
+	shallow = true
 
 [submodule "components/bootloader/subproject/components/micro-ecc/micro-ecc"]
 	path = components/bootloader/subproject/components/micro-ecc/micro-ecc
@@ -80,6 +81,7 @@
 [submodule "components/esp_wifi/lib"]
 	path = components/esp_wifi/lib
 	url = ../../espressif/esp32-wifi-lib.git
+	shallow = true
 
 [submodule "components/cmock/CMock"]
 	path = components/cmock/CMock
@@ -97,30 +99,37 @@
 [submodule "components/bt/controller/lib_esp32c3_family"]
 	path = components/bt/controller/lib_esp32c3_family
 	url = ../../espressif/esp32c3-bt-lib.git
+	shallow = true
 
 [submodule "components/esp_phy/lib"]
 	path = components/esp_phy/lib
 	url = ../../espressif/esp-phy-lib.git
+	shallow = true
 
 [submodule "components/openthread/lib"]
 	path = components/openthread/lib
 	url = ../../espressif/esp-thread-lib.git
+	shallow = true
 
 [submodule "components/bt/controller/lib_esp32h2/esp32h2-bt-lib"]
 	path = components/bt/controller/lib_esp32h2/esp32h2-bt-lib
 	url = ../../espressif/esp32h2-bt-lib.git
+	shallow = true
 
 [submodule "components/bt/controller/lib_esp32c2/esp32c2-bt-lib"]
 	path = components/bt/controller/lib_esp32c2/esp32c2-bt-lib
 	url = ../../espressif/esp32c2-bt-lib.git
+	shallow = true
 
 [submodule "components/bt/controller/lib_esp32c6/esp32c6-bt-lib"]
 	path = components/bt/controller/lib_esp32c6/esp32c6-bt-lib
 	url = ../../espressif/esp32c6-bt-lib.git
+	shallow = true
 
 [submodule "components/bt/controller/lib_esp32c5/esp32c5-bt-lib"]
 	path = components/bt/controller/lib_esp32c5/esp32c5-bt-lib
 	url = ../../espressif/esp32c5-bt-lib.git
+	shallow = true
 
 [submodule "components/heap/tlsf"]
 	path = components/heap/tlsf
@@ -129,7 +138,9 @@
 [submodule "components/esp_coex/lib"]
 	path = components/esp_coex/lib
 	url = ../../espressif/esp-coex-lib.git
+	shallow = true
 
 [submodule "components/bt/esp_ble_mesh/lib/lib"]
 	path = components/bt/esp_ble_mesh/lib/lib
 	url = ../../espressif/esp-ble-mesh-lib.git
+	shallow = true

docs/conf_common.py

@@ -14,6 +14,7 @@ from pathlib import Path
 from esp_docs.conf_docs import *  # noqa: F403,F401
 
 sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), '..', 'tools', 'cmakev2')))
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), '..', 'tools', 'docs')))
 
 if os.environ.get('IDF_PATH') is None:
     raise RuntimeError('IDF_PATH should be set, run export.sh before building docs')
@@ -415,13 +416,13 @@ extensions += [  # noqa: F405
     'esp_docs.idf_extensions.build_system',
     'esp_docs.idf_extensions.esp_err_definitions',
     'esp_docs.idf_extensions.gen_defines',
-    'esp_docs.idf_extensions.gen_version_specific_includes',
     'esp_docs.idf_extensions.kconfig_reference',
     'esp_docs.idf_extensions.gen_idf_tools_links',
     'esp_docs.esp_extensions.run_doxygen',
     'esp_docs.esp_extensions.add_html_zip',
     'linuxdoc.rstFlatTable',  # https://return42.github.io/linuxdoc/linuxdoc-howto/table-markup.html#flat-table
     'esp_docs_cmakev2_extension',
+    'gen_version_specific_includes',
 ]
 
 # Use wavedrompy as backend, instead of wavedrom-cli

docs/en/get-started/linux-macos-setup.rst

@@ -129,6 +129,10 @@ Open Terminal, and run the following commands:
 
 .. include-build-file:: inc/git-clone-bash.inc
 
+.. note::
+
+    If your internet connection is slow, you can add the ``--depth 1`` option to the ``git clone`` command to download the latest commit only. However, this will make subsequent ``git fetch`` operations slower and download more data than necessary.
+
 ESP-IDF is downloaded into ``~/esp/esp-idf``.
 
 Consult :doc:`/versions` for information about which ESP-IDF version to use in a given situation.

docs/zh_CN/get-started/linux-macos-setup.rst

@@ -129,6 +129,10 @@ Apple M1 用户
 
 .. include-build-file:: inc/git-clone-bash.inc
 
+.. note::
+
+    如果网络连接较慢，可以在 ``git clone`` 命令中添加 ``--depth 1`` 选项，仅下载最新提交。但这样会导致后续的 ``git fetch`` 操作变慢，下载更多不必要的数据。
+
 ESP-IDF 将下载至 ``~/esp/esp-idf``。
 
 请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。

tools/ci/exclude_check_tools_files.txt

@@ -43,6 +43,7 @@ tools/ci/python_packages/wifi_tools.py
 tools/ci/sg_rules/*
 tools/ci/sort_yaml.py
 tools/ci/utils.sh
+tools/docs/gen_version_specific_includes.py
 tools/eclipse-code-style.xml
 tools/format.sh
 tools/gdb_panic_server.py

tools/ci/executable-list.txt

@@ -85,6 +85,7 @@ tools/ci/sort_yaml.py
 tools/ci/test_autocomplete/test_autocomplete.py
 tools/ci/test_configure_ci_environment.sh
 tools/docker/entrypoint.sh
+tools/docs/gen_version_specific_includes.py
 tools/esp_app_trace/logtrace_proc.py
 tools/esp_app_trace/sysviewtrace_proc.py
 tools/esp_app_trace/test/logtrace/test.sh

tools/docs/gen_version_specific_includes.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python
+#
+# SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Apache-2.0
+#
+# Sphinx extension to generate ReSTructured Text .inc snippets
+# with version-based content for this IDF version
+
+import os
+import re
+import subprocess
+from typing import Any
+from typing import cast
+
+from esp_docs.util.util import copy_if_modified
+
+TEMPLATES = {
+    'en': {
+        'git-clone-bash': """
+.. code-block:: bash
+
+    mkdir -p ~/esp
+    cd ~/esp
+    git clone %(clone_args)s--single-branch --recursive https://github.com/espressif/esp-idf.git
+        """,
+        'version-note': {
+            'master': """
+.. note::
+
+     This is documentation for the master branch (latest version) of ESP-IDF.
+     This version is under continual development. `Stable version`_ documentation
+     is available, as well as other :doc:`/versions`.
+""",
+            'stable': """
+.. note::
+
+     This is documentation for stable version %s of ESP-IDF.
+     Other :doc:`/versions` are also available.
+""",
+            'branch': """
+.. note::
+
+     This is documentation for %s ``%s`` of ESP-IDF.
+     Other :doc:`/versions` are also available.
+""",
+        },  # version-note
+    },  # en
+    'zh_CN': {
+        'git-clone-bash': """
+.. code-block:: bash
+
+    mkdir -p ~/esp
+    cd ~/esp
+    git clone %(clone_args)s--single-branch --recursive https://github.com/espressif/esp-idf.git
+            """,
+        'version-note': {
+            'master': """
+.. note::
+
+     这是 ESP-IDF master 分支（最新版本）的文档，该版本在持续开发中。还有
+     `Stable version`_ 的文档，以及其他版本的文档 :doc:`/versions` 供参考。
+""",
+            'stable': """
+.. note::
+
+     这是 ESP-IDF 稳定版本 %s 的文档，还有其他版本的文档 :doc:`/versions` 供参考。
+""",
+            'branch': """
+.. note::
+
+     这是 ESP-IDF %s ``%s`` 版本的文档，还有其他版本的文档 :doc:`/versions` 供参考。
+""",
+        },  # version-note
+    },  # zh_CN
+}
+
+
+def setup(app: Any) -> dict[str, Any]:
+    # doesn't need to be this event specifically, but this is roughly the right time
+    app.connect('project-build-info', generate_version_specific_includes)
+    return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'}
+
+
+def generate_version_specific_includes(app: Any, project_description: Any) -> None:
+    language = app.config.language
+    tmp_out_dir = os.path.join(app.config.build_dir, 'version_inc')
+    if not os.path.exists(tmp_out_dir):
+        print(f'Creating directory {tmp_out_dir}')
+        os.mkdir(tmp_out_dir)
+
+    template = TEMPLATES[language]
+
+    version, ver_type, is_stable = get_version()
+
+    write_git_clone_inc_files(template, tmp_out_dir, version, ver_type, is_stable)
+    version_note_template = cast(dict[str, Any], template['version-note'])
+    write_version_note(version_note_template, tmp_out_dir, version, ver_type, is_stable)
+    copy_if_modified(tmp_out_dir, os.path.join(app.config.build_dir, 'inc'))
+    print('Done')
+
+
+def write_git_clone_inc_files(
+    template: dict[str, Any], out_dir: str, version: str, ver_type: str, is_stable: bool
+) -> None:
+    def out_file(basename: str) -> str:
+        p = os.path.join(out_dir, f'{basename}.inc')
+        print(f'Writing {p}...')
+        return p
+
+    if version == 'master':
+        clone_args = ''
+    else:
+        clone_args = f'-b {version} '
+
+    with open(out_file('git-clone-bash'), 'w', encoding='utf-8') as f:
+        f.write(template['git-clone-bash'] % locals())
+
+    print('Wrote git-clone-xxx.inc files')
+
+
+def write_version_note(template: dict[str, Any], out_dir: str, version: str, ver_type: str, is_stable: bool) -> None:
+    if version == 'master':
+        content = template['master']
+    elif ver_type == 'tag' and is_stable:
+        content = template['stable'] % version
+    else:
+        content = template['branch'] % (ver_type, version)
+    out_file = os.path.join(out_dir, 'version-note.inc')
+    with open(out_file, 'w', encoding='utf-8') as f:
+        f.write(content)
+    print(f'{out_file} written')
+
+
+def get_version() -> tuple[str, str, bool]:
+    """
+    Returns a tuple of (name of branch/tag/commit-id, type branch/tag/commit, is_stable)
+    """
+    # Use git to look for a tag
+    try:
+        tag = subprocess.check_output(['git', 'describe', '--exact-match']).strip().decode('utf-8')
+        is_stable = re.match(r'v[0-9\.]+$', tag) is not None
+        return (tag, 'tag', is_stable)
+    except subprocess.CalledProcessError:
+        pass
+
+    # No tag, look at branch name from CI, this will give the correct branch name even if the ref for the branch we
+    # merge into has moved forward before the pipeline runs
+    branch = os.environ.get('CI_COMMIT_REF_NAME', None)
+    if branch is not None:
+        return (branch, 'branch', False)
+
+    # Try to find the branch name even if docs are built locally
+    branch = subprocess.check_output(['git', 'rev-parse', '--abbrev-ref', 'HEAD']).strip().decode('utf-8')
+    if branch != 'HEAD':
+        return (branch, 'branch', False)
+
+    # As a last resort we return commit SHA-1, should never happen in CI/docs that should be published
+    return (subprocess.check_output(['git', 'rev-parse', '--short', 'HEAD']).strip().decode('utf-8'), 'commit', False)