diff --git a/.gitmodules b/.gitmodules index 86ec4a3da5..7918278150 100644 --- a/.gitmodules +++ b/.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 diff --git a/docs/conf_common.py b/docs/conf_common.py index 47d9a43a10..4c67122152 100644 --- a/docs/conf_common.py +++ b/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 diff --git a/docs/en/get-started/linux-macos-setup.rst b/docs/en/get-started/linux-macos-setup.rst index 7848bf6e6a..016046756e 100644 --- a/docs/en/get-started/linux-macos-setup.rst +++ b/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. diff --git a/docs/zh_CN/get-started/linux-macos-setup.rst b/docs/zh_CN/get-started/linux-macos-setup.rst index abe4bb6498..8f3e7ca311 100644 --- a/docs/zh_CN/get-started/linux-macos-setup.rst +++ b/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 不同版本的具体适用场景。 diff --git a/tools/ci/exclude_check_tools_files.txt b/tools/ci/exclude_check_tools_files.txt index 7b5ec92c21..66fdcfb88c 100644 --- a/tools/ci/exclude_check_tools_files.txt +++ b/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 diff --git a/tools/ci/executable-list.txt b/tools/ci/executable-list.txt index 1870cbeac0..82763cedea 100644 --- a/tools/ci/executable-list.txt +++ b/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 diff --git a/tools/docs/gen_version_specific_includes.py b/tools/docs/gen_version_specific_includes.py new file mode 100755 index 0000000000..7ed09a2e67 --- /dev/null +++ b/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)