diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 672f4e9a66..8b3a502307 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -63,7 +63,7 @@ variables: CI_AUTO_TEST_SCRIPT_REPO_BRANCH: "ci/v3.1" # Versioned esp-idf-doc env image to use for all document building jobs - ESP_IDF_DOC_ENV_IMAGE: "$CI_DOCKER_REGISTRY/esp-idf-doc-env:v8" + ESP_IDF_DOC_ENV_IMAGE: "$CI_DOCKER_REGISTRY/esp-idf-doc-env:v10" .setup_tools_unless_target_test: &setup_tools_unless_target_test | if [[ -n "$IDF_DONT_USE_MIRRORS" ]]; then diff --git a/docs/_static/choose_language.png b/docs/_static/choose_language.png new file mode 100644 index 0000000000..9b24c1faa9 Binary files /dev/null and b/docs/_static/choose_language.png differ diff --git a/docs/_static/choose_version.png b/docs/_static/choose_version.png index c8927df118..ad479c7fd9 100644 Binary files a/docs/_static/choose_version.png and b/docs/_static/choose_version.png differ diff --git a/docs/_static/js/version_table.js b/docs/_static/js/version_table.js new file mode 100644 index 0000000000..5e0c4cba58 --- /dev/null +++ b/docs/_static/js/version_table.js @@ -0,0 +1,54 @@ +$(document).ready(function() { + + let version = DOCUMENTATION_OPTIONS.VERSION; + let language = DOCUMENTATION_OPTIONS.LANGUAGE; + let idf_target = DOCUMENTATION_OPTIONS.IDF_TARGET; + let pagename = DOCUMENTATION_OPTIONS.PAGENAME + ".html"; + + let defaults = DOCUMENTATION_VERSIONS.DEFAULTS; + let versions = DOCUMENTATION_VERSIONS.VERSIONS; + + /* Apply the defaults to each version, where needed */ + for (let i = 0; i < versions.length; i++) { + let v = versions[i]; + for (let d in defaults) { + if (!(d in v)) { + v[d] = defaults[d]; + } + } + } + + /* Find the (relative) base URL for this project, finding a sibling URL will be built as follows: + /// + + (Where 'idf_target' path element are optional depending on if the project has multiple target support) + */ + let project_base_url = DOCUMENTATION_OPTIONS.URL_ROOT + "../../.."; + if (DOCUMENTATION_OPTIONS.IDF_TARGETS) { + project_base_url += "/.."; + } + + /* Given a version from the list, return the URL to link to it */ + function getVersionUrl(v) { + let result = project_base_url + "/" + language + "/" + v.name; + if (v.has_targets) { + result += "/" + (idf_target || "esp32"); + } + + return result + "/"; + }; + + old_ver_list = ""; + + for (let i = 0; i < versions.length; i++) { + let v = versions[i]; + let url = getVersionUrl(v); + + if (v.old) { + old_ver_list += "
  • " + v.name + "
    • "; + } + + } + + $( "#version_list" ).append(old_ver_list); +}); diff --git a/docs/_static/version_table.html b/docs/_static/version_table.html new file mode 100644 index 0000000000..6e0feedbbe --- /dev/null +++ b/docs/_static/version_table.html @@ -0,0 +1,7 @@ + + + +
      + +
    +     diff --git a/docs/conf_common.py b/docs/conf_common.py index cf5f1418f9..c055657a71 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -59,6 +59,7 @@ extensions = ['breathe', 'extensions.html_redirects', 'extensions.toctree_filter', 'extensions.list_filter', + 'extensions.google_analytics', # Note: order is important here, events must # be registered by one extension before they can be @@ -361,6 +362,8 @@ html_static_path = ['../_static'] # Output file base name for HTML help builder. htmlhelp_basename = 'ReadtheDocsTemplatedoc' +google_analytics_id = os.environ['CI_GOOGLE_ANALYTICS_ID'] + # -- Options for LaTeX output --------------------------------------------- latex_template_dir = os.path.join(config_dir, 'latex_templates') diff --git a/docs/en/index.rst b/docs/en/index.rst index 547c663db2..a2731a9518 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -6,7 +6,7 @@ This is the documentation for Espressif IoT Development Framework (`esp-idf `_ -(major, minor, bugfix, etc). +The ESP-IDF Programming Guide has information about the `different versions of ESP-IDF `_ (major, minor, bugfix, etc). .. image:: https://dl.espressif.com/dl/esp-idf/support-periods.svg diff --git a/docs/extensions/google_analytics.py b/docs/extensions/google_analytics.py new file mode 100644 index 0000000000..e565318169 --- /dev/null +++ b/docs/extensions/google_analytics.py @@ -0,0 +1,30 @@ +# Embeds a google analytics tracking tag in every HTML page +def setup(app): + app.add_config_value('google_analytics_id', None, 'html') + app.connect('html-page-context', google_analytics_embed) + + return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'} + + +def google_analytics_embed(app, pagename, templatename, context, doctree): + + ga_id = app.config.google_analytics_id + if not ga_id: + return + + metatags = context.get('metatags', '') + + google_analytics_snippet = """ + + + """.format(ga_id, ga_id) + + # Prepend the google analytics to the HTML metatags (which will be passed to the sphinx templating engine) + metatags = google_analytics_snippet + metatags + context['metatags'] = metatags diff --git a/docs/requirements.txt b/docs/requirements.txt index 6802c11198..930e8d10a5 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -19,4 +19,4 @@ nwdiag==2.0.0 recommonmark future>=0.16.0 # for ../tools/gen_esp_err_to_name.py sphinx_selective_exclude==1.0.3 -sphinx_idf_theme==0.2 +sphinx_idf_theme==0.3.0 diff --git a/docs/zh_CN/index.rst b/docs/zh_CN/index.rst index f32f7e88b8..3c46d468de 100644 --- a/docs/zh_CN/index.rst +++ b/docs/zh_CN/index.rst @@ -6,7 +6,7 @@ ESP-IDF 编程指南 .. only:: html - 本文档仅包含针对 {IDF_TARGET_NAME} 芯片的 ESP-IDF 使用。如需了解其他芯片，请点击页面左下方的 "Switch Version"。 + 本文档仅包含针对 {IDF_TARGET_NAME} 芯片的 ESP-IDF 使用。如需了解其他芯片，请在页面左上方的下拉菜单中选择您的目标芯片。 .. only:: latex diff --git a/docs/zh_CN/languages.rst b/docs/zh_CN/languages.rst index bb384e9eee..4ecb79cc12 100644 --- a/docs/zh_CN/languages.rst +++ b/docs/zh_CN/languages.rst @@ -1 +1,14 @@ -.. include:: ../en/languages.rst +切换语言 +================================= + +:link_to_translation:`en:[English]` + +《ESP-IDF 编程指南》部分文档现在有两种语言的版本。如有出入请以英文版本为准。 + +- 英文 +- 中文 + +如下图所示，如果该文档两种语言版本均具备，您可以通过点击文档上方的语言链接轻松进行语言切换。 + +.. image:: /../_static/choose_language.png + diff --git a/docs/zh_CN/versions.rst b/docs/zh_CN/versions.rst index 4d62b675f1..ea58b47e25 100644 --- a/docs/zh_CN/versions.rst +++ b/docs/zh_CN/versions.rst @@ -19,13 +19,23 @@ ESP-IDF 的 GitHub 仓库时常更新，特别是用于开发新特性的 master ESP-IDF 在 GitHub 平台上的完整发布历史请见 `发布说明页面`_。您可以在该页面查看各个版本的发布说明、配套文档及相应获取方式。 -此外，您还可以直接前往文档页面，查看部分 ESP-IDF 版本的配套文档，具体可通过点击页面左下角的小三角标志，在不同版本间切换。 -.. image:: /../_static/choose_version.png +.. only:: html + + 此外，您还可以直接前往文档页面，查看不同 ESP-IDF 版本的配套文档，具体可点击页面左上角中版本的下拉菜单（在目标下拉菜单和搜索栏之间），实现在不同版本间切换。 + + .. image:: /../_static/choose_version.png + + 旧版本的文档也仍然可用： + + .. raw:: html + :file: ../_static/version_table.html + + 我该选择哪个版本？ ----------------------------------- +---------------------- - 如有量产需求，请使用 `最新稳定版本`_ 。稳定版本已通过人工测试，后续更新仅修复 bug，主要特性不受影响（更多详情，请见 `版本管理`_ ）。请访问 `发布说明页面`_ 界面查看每一个稳定发布版本。 @@ -35,7 +45,6 @@ ESP-IDF 在 GitHub 平台上的完整发布历史请见 `发布说明页面`_。 有关如何更新 ESP-IDF 本地副本的内容，请参考 :ref:`updating` 章节。 - 版本管理 ----------------- @@ -56,7 +65,7 @@ ESP-IDF 采用了 `语义版本管理方法 `_，即您可 支持期限 --------------- -ESP-IDF 的每个主要版本和次要版本都有相应的支持期限。支持期限满后，版本停止更新维护，将不再支持。 +ESP-IDF 的每个主要版本和次要版本都有相应的支持期限。支持期限满后，版本停止更新维护，将不再提供支持。 `支持期限政策`_ 对此有具体描述，并介绍了每个版本的支持期限是如何界定的。 @@ -65,10 +74,46 @@ ESP-IDF 的每个主要版本和次要版本都有相应的支持期限。支持 一般而言： - 如您刚开始一个新项目，建议使用最新稳定版本。 -- 如您有 GitHub 账号，请点击 `发布说明页面`_ 界面右上角的 "Watch" 按键，并选中 "Releases only" 选项。GitHub 将会在新版本发布的时候通知您。当您所使用的版本有 bugfix 版本发布时，请做好升级至该 bugfix 版本的规划。 -- 如可能，请定期（如每年一次）将项目的 IDF 版本升级至一个新的主要版本或次要版本。对于小版本更新，更新过程应该比较简单，但对于主要版本更新，可能需要细致查看发布说明并做对应的更新规划。 +- 如您有 GitHub 账号，请点击 `发布说明页面`_ 界面右上角的 "Watch" 按键，并选中 "Releases only" 选项。GitHub 将会在新版本发布的时候通知您。当您所使用的版本有 Bugfix 版本发布时，请做好升级至该 Bugfix 版本的规划。 +- 如可能，请定期（如每年一次）将项目的 IDF 版本升级至一个新的主要版本或次要版本。对于次要版本更新，更新过程应该比较简单，但对于主要版本更新，可能需要细致查看发布说明并做对应的更新规划。 - 请确保您所使用的版本停止更新维护前，已做好升级至新版本的规划。 +ESP-IDF 的每个主要版本和次要版本（V4.1、V4.2 等）的支持期限为 30 个月，从最初的稳定版发布日算起。 + +在支持期限内意味着 ESP-IDF 团队将继续在 GitHub 的发布分支上进行 bug 修复、安全修复等，并根据需要定期发布新的 Bugfix 版本。 + +支持期限分为“服务期”和“维护期”： + +.. list-table:: + :header-rows: 1 + :widths: 25 25 55 + + * - 周期 + - 时长 + - 是否推荐新工程使用 + * - 服务期 + - 12 个月 + - 是 + * - 维护期 + - 18 个月 + - 否 + +在服务期内，Bugfix 版本的发布更为频繁。某些情况下，在服务期内会增加新特性，这些特性主要是为了满足新产品特定监管要求或标准，并且回归风险非常低。 + +在维护期内，该版本仍受支持，但只会对严重性较高的问题或安全问题进行 bug 修复。 + +当开始一个新项目时，建议使用在服务期内的版本。 + +鼓励用户在您所用的版本支持期限结束之前，将所有的工程升级到最新的 ESP-IDF 版本。在版本支持期限满后，我们将不再继续进行 bug 修复。 + +支持期限不包括预发布版本（betas、预览版、 `-rc` 和 `-dev` 版等），有时会将某个特性在发布版中标记为“预览版”，这意味着该特性也不在支持期限内。 + +关于 `不同版本的 ESP-IDF `_ （主要版本、次要版本、Bugfix 版本等）的更多信息，请参考 ESP-IDF 编程指南。 + + +.. image:: https://dl.espressif.com/dl/esp-idf/support-periods.svg + + 查看当前版本 ---------------------------- @@ -78,6 +123,8 @@ ESP-IDF 的每个主要版本和次要版本都有相应的支持期限。支持 此外，由于 ESP-IDF 的版本也已编译至固件中，因此您也可以使用宏 ``IDF_VER`` 查看 ESP-IDF 的版本（以字符串的格式）。ESP-IDF 默认引导程序会在设备启动时打印 ESP-IDF 的版本。请注意，在 GitHub 仓库中的代码更新时，代码中的版本信息仅会在源代码重新编译或在清除编译时才会更新，因此打印出来的版本可能并不是最新的。 +如果编写的代码需要支持多个 ESP-IDF 版本，可以在编译时使用 :ref:`compile-time macros` 检查版本。 + 几个 ESP-IDF 版本的例子： =============================== =================================================================================================== @@ -97,7 +144,6 @@ ESP-IDF 的每个主要版本和次要版本都有相应的支持期限。支持 | - ``dirty`` 代表 ESP-IDF 的本地副本有修改。 =============================== =================================================================================================== - Git 工作流 ------------ @@ -105,15 +151,16 @@ Git 工作流 - 新的改动总是在 master 分支（最新版本）上进行。master 分支上的 ESP-IDF 版本总带有 ``-dev`` 标签，表示“正在开发中”，例 ``v3.1-dev``。 - 这些改动将首先在乐鑫的内部 Git 仓库进行代码审阅与测试，而后在自动化测试完成后推至 GitHub。 -- 新版本一旦完成特性开发（在 ``master`` 分支上进行）并达到进入 beta 测试的标准，则将该版本签出至一个新分支（例 ``release/v3.1``）。此外，该分支还打上预发布标签（例 ``v3.1-beta1``）。您可以在 GitHub 平台上查看 ESP-IDF 的完整 `分支列表`_ 和 `标签列表`_。Beta 预发布版本可能仍存在大量“已知问题”(Known Issue)。 +- 新版本一旦完成特性开发（在 ``master`` 分支上进行）并达到进入 beta 测试的标准，则将该版本切换至一个新分支（例 ``release/v3.1``）。此外，该分支还打上预发布标签（例 ``v3.1-beta1``）。您可以在 GitHub 平台上查看 ESP-IDF 的完整 `分支列表`_ 和 `标签列表`_。Beta 预发布版本可能仍存在大量“已知问题”(Known Issue)。 - 随着对 beta 版本的不断测试，bug 修复将同时增加至该发布分支和 ``master`` 分支。而且，``master`` 分支可能也已经开始为下个版本开发新特性了。 - 当测试快结束时，该发布分支上将增加一个 rc 标签，代表候选发布 (Release Candidate) ，例 ``v3.1-rc1``。此时，该分支仍属于预发布版本。 - 如果一直未发现或报告重大 bug，则该预发布版本将最终增加“主要版本”（例 ``v4.0``）或“次要版本”标记（例 ``v3.1``），成为正式发布版本，并体现在 `发布说明页面`_ 。 -- 后续，该版本中发现的 bug 都将在该发布分支上进行修复。人工测试完成后，该分支将增加一个 bugfix 版本标签（例 ``v3.1.1``），并体现在 `发布说明页面`_ 。 +- 后续，该版本中发现的 bug 都将在该发布分支上进行修复。人工测试完成后，该分支将增加一个 Bugfix 版本标签（例 ``v3.1.1``），并体现在 `发布说明页面`_ 。 .. _updating: + 更新 ESP-IDF ---------------- @@ -131,10 +178,10 @@ Git 工作流 更新至一个稳定发布版本 ^^^^^^^^^^^^^^^^^^^^^^^^^^ -（推荐量产用户）如需更新至一个新的 ESP-IDF 发布版本，请参考以下步骤： +对于量产用户，推荐更新至一个新的 ESP-IDF 发布版本，请参考以下步骤： - 请定期查看 `发布说明页面`_ ，了解最新发布情况。 -- 如有新发布的 bugfix 版本（例 ``v3.0.1`` 或 ``v3.0.2``）时，请将新的 bugfix 版本更新至您的 ESP-IDF 目录： +- 如有新发布的 Bugfix 版本（例 ``v3.0.1`` 或 ``v3.0.2``）时，请将新的 Bugfix 版本更新至您的 ESP-IDF 目录： .. code-block:: bash @@ -143,7 +190,7 @@ Git 工作流 git checkout vX.Y.Z git submodule update --init --recursive -- 如有主要版本或次要版本新发布时，请查看发布说明中的具体描述，并决定是否升级您的版本。具体命令与上方描述一致。 +- 在主要版本或次要版本新发布时，请查看发布说明中的具体描述，并决定是否升级您的版本。具体命令与上方描述一致。 .. note:: 如果您之前在安装 ESP-IDF 时使用了 zip 文件包，而非通过 Git 命令，则您将无法使用 Git 命令进行版本升级，此属正常情况。这种情况下，请重新下载最新 zip 文件包，并替换掉之前 ``IDF_PATH`` 下的全部内容。 @@ -153,7 +200,7 @@ Git 工作流 更新至一个预发布版本 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -您也可以将您的本地副本签出（命令 ``git checkout``）至一个预发布版本或 rc 版本，具体方法请参考 :ref:`更新至一个稳定发布版本` 中的描述。 +您也可以将您的本地副本切换（命令 ``git checkout``）至一个预发布版本或 rc 版本，具体方法请参考 :ref:`更新至一个稳定发布版本` 中的描述。 预发布版本通常不体现在 `发布说明页面`_。更多详情，请查看完整 `标签列表`_。使用预发布版本的注意事项，请参考 :ref:`更新至一个发布分支` 中的描述。 @@ -166,14 +213,14 @@ Git 工作流 如需使用 ESP-IDF 的 master 分支，请参考以下步骤： -- 本地签出至 master 分支:: +- 本地切换至 master 分支:: cd $IDF_PATH git checkout master git pull git submodule update --init --recursive -- 此外，您还应在后续工作中不时使用 ``git pull`` 命令，将远端 master 上的更新同步到本地。注意，在更新 master 分支后，您可能需要更改项代码，也可能遇到新的 bug。 +- 此外，您还应在后续工作中不时使用 ``git pull`` 命令，将远端 master 上的更新同步到本地。注意，在更新 master 分支后，您可能需要更改工程代码，也可能遇到新的 bug。 - 如需从 master 分支切换至一个发布分支或稳定版本，请使用 ``git checkout`` 命令。 .. important:: 强烈建议您定期使用 ``git pull`` 和 ``git submodule update --init --recursive`` 命令，确保本地副本的及时更新。旧的 master 分支相当于一个“快照”，可能存在未记录的问题，且无法获得支持。对于半稳定版本，请参考 :ref:`更新至一个发布分支`。 @@ -187,7 +234,7 @@ Git 工作流 更多详情，请前往 GitHub 查看完整 `标签列表`_。 -举例，您可以关注 ESP-IDF v3.1 分支，随时关注该分支上的 bugfix 版本发布（ 例 ``v3.1.1`` 等）:: +举例，您可以关注 ESP-IDF v3.1 分支，随时关注该分支上的 Bugfix 版本发布（ 例 ``v3.1.1`` 等）:: cd $IDF_PATH git fetch @@ -195,9 +242,9 @@ Git 工作流 git pull git submodule update --init --recursive -您每次在该分支上使用 ``git pull`` 时都相当于把最新的 bugfix 版本发布更新至您的本地副本中。 +您每次在该分支上使用 ``git pull`` 时都相当于把最新的 Bugfix 版本发布更新至您的本地副本中。 -.. note:: 发布分支并不会有专门的配套文档，建议您使用与本分支最接近的版本。 +.. note:: 发布分支并不会有专门的配套文档，建议您使用与本分支最接近版本的文档。 .. _`发布说明页面`: http://github.com/espressif/esp-idf/releases .. _`分支列表`: https://github.com/espressif/esp-idf/branches