From 79fbf6b2d465b29c71f956a16167424bb81ae938 Mon Sep 17 00:00:00 2001 From: Wang Ning Date: Fri, 10 Apr 2026 19:07:03 +0800 Subject: [PATCH] docs: add flowchart for get-started --- .../get-started-esp-idf-develop-zh.diag | 30 ++++++++++ docs/_static/get-started-esp-idf-develop.diag | 30 ++++++++++ .../_static/get-started-esp-idf-setup-zh.diag | 28 +++++++++ docs/_static/get-started-esp-idf-setup.diag | 28 +++++++++ docs/en/get-started/index.rst | 57 +++++++------------ docs/en/get-started/uninstall.rst | 39 +++++++++++++ docs/en/get-started/workflow-overview.rst | 51 +++++++++++++++++ docs/zh_CN/get-started/index.rst | 57 +++++++------------ docs/zh_CN/get-started/uninstall.rst | 39 +++++++++++++ docs/zh_CN/get-started/workflow-overview.rst | 51 +++++++++++++++++ 10 files changed, 338 insertions(+), 72 deletions(-) create mode 100644 docs/_static/get-started-esp-idf-develop-zh.diag create mode 100644 docs/_static/get-started-esp-idf-develop.diag create mode 100644 docs/_static/get-started-esp-idf-setup-zh.diag create mode 100644 docs/_static/get-started-esp-idf-setup.diag create mode 100644 docs/en/get-started/uninstall.rst create mode 100644 docs/en/get-started/workflow-overview.rst create mode 100644 docs/zh_CN/get-started/uninstall.rst create mode 100644 docs/zh_CN/get-started/workflow-overview.rst diff --git a/docs/_static/get-started-esp-idf-develop-zh.diag b/docs/_static/get-started-esp-idf-develop-zh.diag new file mode 100644 index 00000000000..4531b549b28 --- /dev/null +++ b/docs/_static/get-started-esp-idf-develop-zh.diag @@ -0,0 +1,30 @@ +blockdiag { + orientation = portrait; + edge_layout = flowchart; + shadow_style = none; + node_width = 170; + node_height = 80; + span_width = 50; + span_height = 50; + default_fontsize = 22; + + build_method [label = "如何构建项目？\nIDE 或 CLI", shape = diamond, width = 300, height = 170]; + open_ide [label = "打开 IDE", width = 170, height = 80, shape = roundedbox]; + activate_cli [label = "激活 CLI 环境", width = 170, height = 80, shape = roundedbox]; + start_project [label = "创建项目", width = 170, height = 80, shape = roundedbox]; + connect [label = "连接设备", width = 170, height = 80, shape = roundedbox]; + configure [label = "配置项目", width = 170, height = 80, shape = roundedbox]; + build [label = "编译", width = 170, height = 80, shape = roundedbox]; + flash [label = "烧录", width = 170, height = 80, shape = roundedbox]; + monitor [label = "监视输出", width = 170, height = 80, shape = roundedbox]; + + build_method -> open_ide [label = "IDE"]; + build_method -> activate_cli [label = "CLI"]; + activate_cli -> start_project; + open_ide -> start_project; + start_project -> connect; + connect -> configure; + configure -> build; + build -> flash; + flash -> monitor; +} diff --git a/docs/_static/get-started-esp-idf-develop.diag b/docs/_static/get-started-esp-idf-develop.diag new file mode 100644 index 00000000000..882e6f5056f --- /dev/null +++ b/docs/_static/get-started-esp-idf-develop.diag @@ -0,0 +1,30 @@ +blockdiag { + orientation = portrait; + edge_layout = flowchart; + shadow_style = none; + node_width = 170; + node_height = 80; + span_width = 50; + span_height = 50; + default_fontsize = 22; + + build_method [label = "Build with\nIDE or CLI?", shape = diamond, width = 260, height = 140]; + open_ide [label = "Open IDE", width = 160, height = 70, shape = roundedbox]; + activate_cli [label = "Activate CLI\nenvironment", width = 180, height = 90, shape = roundedbox]; + start_project [label = "Start a project", width = 200, height = 70, shape = roundedbox]; + connect [label = "Connect\ndevice", width = 170, height = 80, shape = roundedbox]; + configure [label = "Configure\nproject", width = 170, height = 80, shape = roundedbox]; + build [label = "Build", width = 170, height = 70, shape = roundedbox]; + flash [label = "Flash", width = 170, height = 70, shape = roundedbox]; + monitor [label = "Monitor\noutput", width = 170, height = 80, shape = roundedbox]; + + build_method -> open_ide [label = "IDE"]; + build_method -> activate_cli [label = "CLI"]; + activate_cli -> start_project; + open_ide -> start_project; + start_project -> connect; + connect -> configure; + configure -> build; + build -> flash; + flash -> monitor; +} diff --git a/docs/_static/get-started-esp-idf-setup-zh.diag b/docs/_static/get-started-esp-idf-setup-zh.diag new file mode 100644 index 00000000000..0f9d6732b9a --- /dev/null +++ b/docs/_static/get-started-esp-idf-setup-zh.diag @@ -0,0 +1,28 @@ +blockdiag { + orientation = portrait; + edge_layout = flowchart; + shadow_style = none; + node_width = 170; + node_height = 80; + span_width = 50; + span_height = 50; + default_fontsize = 22; + + start [label = "", shape = beginpoint, width = 40, height = 40]; + ide_first [label = "从 IDE 开始?", shape = diamond, width = 280, height = 140]; + install_ide [label = "安装 IDE 和插件", width = 180, height = 90, shape = roundedbox]; + skip_ide [label = "下一步", width = 180, height = 90, shape = roundedbox]; + prereq [label = "安装依赖包", width = 180, height = 90, shape = roundedbox]; + eim [label = "安装 EIM", width = 180, height = 90, shape = roundedbox]; + install_espidf [label = "使用 EIM 安装\nESP-IDF", width = 200, height = 90, shape = roundedbox]; + build_method [label = "如何构建项目？\nIDE 或 CLI", shape = diamond, width = 300, height = 170, style = dashed]; + + start -> ide_first; + ide_first -> install_ide [label = "是"]; + install_ide -> prereq; + ide_first -> skip_ide [label = "否"]; + skip_ide -> prereq; + prereq -> eim; + eim -> install_espidf; + install_espidf -> build_method; +} diff --git a/docs/_static/get-started-esp-idf-setup.diag b/docs/_static/get-started-esp-idf-setup.diag new file mode 100644 index 00000000000..9de051290ae --- /dev/null +++ b/docs/_static/get-started-esp-idf-setup.diag @@ -0,0 +1,28 @@ +blockdiag { + orientation = portrait; + edge_layout = flowchart; + shadow_style = none; + node_width = 170; + node_height = 80; + span_width = 50; + span_height = 50; + default_fontsize = 22; + + start [label = "", shape = beginpoint, width = 40, height = 40]; + ide_first [label = "Start from\nIDE?", shape = diamond, width = 260, height = 140]; + install_ide [label = "Install IDE\nand plugins", width = 180, height = 90, shape = roundedbox]; + skip_ide [label = "Move to\nnext step", width = 180, height = 90, shape = roundedbox]; + prereq [label = "Install\nprerequisites", width = 180, height = 90, shape = roundedbox]; + eim [label = "Install EIM", width = 180, height = 70, shape = roundedbox]; + install_espidf [label = "Install ESP-IDF\nvia EIM", width = 200, height = 90, shape = roundedbox]; + build_method [label = "Build with\nIDE or CLI?", shape = diamond, width = 260, height = 140, style = dashed]; + + start -> ide_first; + ide_first -> install_ide [label = "Yes"]; + install_ide -> prereq; + ide_first -> skip_ide [label = "No"]; + skip_ide -> prereq; + prereq -> eim; + eim -> install_espidf; + install_espidf -> build_method; +} diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst index ea30c026fe1..ec0caed86a6 100644 --- a/docs/en/get-started/index.rst +++ b/docs/en/get-started/index.rst @@ -224,6 +224,24 @@ To start using ESP-IDF on **{IDF_TARGET_NAME}**, you need the following software :alt: Development of applications for {IDF_TARGET_NAME} :figclass: align-center + +Workflow Overview +================= + +Getting started with ESP-IDF involves two main phases: + +1. **Setup** — installing prerequisites and ESP-IDF (see `Installation`_) +2. **Develop** — creating, configuring, building, flashing, and monitoring your project (see `Build Your First Project`_) + +If you are unsure where to start, see :doc:`workflow-overview` for a visual overview of the full workflow. + +.. toctree:: + :maxdepth: 1 + :hidden: + + workflow-overview + + .. _get-started-step-by-step: .. _get-started-how-to-get-esp-idf: .. _get-started-set-up-tools: @@ -289,43 +307,10 @@ Uninstall ESP-IDF To uninstall ESP-IDF and related tools installed via EIM, you can use either the graphical user interface (GUI) or the command line interface (CLI). -Uninstall Using EIM GUI -~~~~~~~~~~~~~~~~~~~~~~~ +.. toctree:: + :maxdepth: 1 -Launch the ESP-IDF Installation Manager. Under ``Manage Installations``, click ``Open Dashboard``. - -.. figure:: ../../_static/get-started-eim-gui.png - :align: center - :alt: Open Dashboard in EIM GUI - :figclass: align-center - - Open Dashboard in EIM GUI - -To remove a specific ESP-IDF version, click the ``Remove`` button under the version you want to remove. - -To remove all ESP-IDF versions, click ``Purge All`` button at the bottom of the page. - -.. figure:: ../../_static/get-started-eim-gui-uninstall.png - :align: center - :alt: Uninstall ESP-IDF in EIM GUI - :figclass: align-center - - Uninstall ESP-IDF in EIM GUI - -Uninstall Using EIM CLI -~~~~~~~~~~~~~~~~~~~~~~~ - -To remove a specific ESP-IDF version, for example v5.4.2, run the following command in your terminal: - -.. code-block:: bash - - eim remove v5.4.2 - -To remove all ESP-IDF versions, run the following command in your terminal: - -.. code-block:: bash - - eim purge + uninstall Related Documents diff --git a/docs/en/get-started/uninstall.rst b/docs/en/get-started/uninstall.rst new file mode 100644 index 00000000000..78aaf65659d --- /dev/null +++ b/docs/en/get-started/uninstall.rst @@ -0,0 +1,39 @@ +Uninstall ESP-IDF Using EIM GUI +================================ + +:link_to_translation:`zh_CN:[中文]` + +Launch the ESP-IDF Installation Manager. Under ``Manage Installations``, click ``Open Dashboard``. + +.. figure:: ../../_static/get-started-eim-gui.png + :align: center + :alt: Open Dashboard in EIM GUI + :figclass: align-center + + Open Dashboard in EIM GUI + +To remove a specific ESP-IDF version, click the ``Remove`` button under the version you want to remove. + +To remove all ESP-IDF versions, click the ``Purge All`` button at the bottom of the page. + +.. figure:: ../../_static/get-started-eim-gui-uninstall.png + :align: center + :alt: Uninstall ESP-IDF in EIM GUI + :figclass: align-center + + Uninstall ESP-IDF in EIM GUI + +Uninstall ESP-IDF Using EIM CLI +================================ + +To remove a specific ESP-IDF version, for example v5.4.2, run the following command in your terminal: + +.. code-block:: bash + + eim remove v5.4.2 + +To remove all ESP-IDF versions, run the following command in your terminal: + +.. code-block:: bash + + eim purge diff --git a/docs/en/get-started/workflow-overview.rst b/docs/en/get-started/workflow-overview.rst new file mode 100644 index 00000000000..de3f220517e --- /dev/null +++ b/docs/en/get-started/workflow-overview.rst @@ -0,0 +1,51 @@ +Workflow Overview +================= + +:link_to_translation:`zh_CN:[中文]` + +The following diagram shows how to set up the environment to use ESP-IDF. The setup flow varies depending on whether you start from an IDE or not, but both paths lead to the same development workflow. + +.. blockdiag:: /../_static/get-started-esp-idf-setup.diag + :caption: ESP-IDF Setup Workflow (Click to enlarge) + :align: center + :scale: 60% + :alt: ESP-IDF Setup Workflow + +The following diagram shows how to develop with ESP-IDF. + +.. blockdiag:: /../_static/get-started-esp-idf-develop.diag + :caption: ESP-IDF Development Workflow (Click to enlarge) + :align: center + :scale: 60% + :alt: ESP-IDF Development Workflow + + +Related Documents +----------------- + +- Setup workflow + + * Install IDE and plugins + + + `Espressif-IDE > Prerequisites `_ + + `Espressif-IDE > Installation `_ + + `ESP-IDF Extension for VS Code > Prerequisites `_ + + `ESP-IDF Extension for VS Code > Install ESP-IDF and Tools `_ + + * Install EIM prerequisites, EIM, and then ESP-IDF via EIM + + + :doc:`windows-setup` + + :doc:`linux-setup` + + :doc:`macos-setup` + +- Development workflow + + * IDE + + + `Espressif-IDE > Start Your Project `_ + + `ESP-IDF Extension for VS Code > Start a Project `_ + + * CLI + + + :doc:`windows-start-project` + + :doc:`linux-macos-start-project` diff --git a/docs/zh_CN/get-started/index.rst b/docs/zh_CN/get-started/index.rst index 1e49259e7f3..7b6c12c4d96 100644 --- a/docs/zh_CN/get-started/index.rst +++ b/docs/zh_CN/get-started/index.rst @@ -224,6 +224,24 @@ :alt: Development of applications for {IDF_TARGET_NAME} :figclass: align-center + +工作流程概览 +============ + +ESP-IDF 的入门流程分为两个主要阶段： + +1. **搭建环境** —— 安装前置依赖和 ESP-IDF（参见 `安装`_） +2. **开发** —— 创建、配置、编译、烧录项目并监视输出（参见 `构建首个项目`_） + +如果不确定从哪里开始，请参见 :doc:`workflow-overview`，查看完整工作流程图示。 + +.. toctree:: + :maxdepth: 1 + :hidden: + + workflow-overview + + .. _get-started-step-by-step: .. _get-started-how-to-get-esp-idf: .. _get-started-set-up-tools: @@ -289,43 +307,10 @@ EIM 提供两种安装方式： 如需卸载通过 EIM 安装的 ESP-IDF 及相关工具，可使用图形用户界面 (GUI) 或命令行界面 (CLI) 两种方式。 -使用 EIM GUI 卸载 -~~~~~~~~~~~~~~~~~ +.. toctree:: + :maxdepth: 1 -启动 ESP-IDF 安装管理器。在 ``管理安装`` 下，点击 ``打开仪表板``。 - -.. figure:: ../../_static/get-started-eim-gui-zh.png - :align: center - :alt: EIM 打开仪表板 - :figclass: align-center - - EIM 打开仪表板 - -如需删除特定 ESP-IDF 版本，请在该版本下点击 ``移除`` 按键。 - -如果删除所有 ESP-IDF 版本，请点击页面底部的 ``清除所有`` 按键。 - -.. figure:: ../../_static/get-started-eim-gui-uninstall-zh.png - :align: center - :alt: EIM 卸载 ESP-IDF - :figclass: align-center - - EIM 卸载 ESP-IDF - -使用 EIM CLI 卸载 -~~~~~~~~~~~~~~~~~ - -如需删除特定 ESP-IDF 版本，例如 v5.4.2，请在终端中运行以下命令： - -.. code-block:: bash - - eim remove v5.4.2 - -如需删除所有 ESP-IDF 版本，请在终端中运行以下命令： - -.. code-block:: bash - - eim purge + uninstall 相关文档 diff --git a/docs/zh_CN/get-started/uninstall.rst b/docs/zh_CN/get-started/uninstall.rst new file mode 100644 index 00000000000..b34569d998f --- /dev/null +++ b/docs/zh_CN/get-started/uninstall.rst @@ -0,0 +1,39 @@ +使用 EIM GUI 卸载 ESP-IDF +========================= + +:link_to_translation:`en:[English]` + +启动 ESP-IDF 安装管理器。在 ``管理安装`` 下，点击 ``打开仪表板``。 + +.. figure:: ../../_static/get-started-eim-gui-zh.png + :align: center + :alt: EIM 打开仪表板 + :figclass: align-center + + EIM 打开仪表板 + +如需删除特定 ESP-IDF 版本，请在该版本下点击 ``移除`` 按键。 + +如需删除所有 ESP-IDF 版本，请点击页面底部的 ``清除所有`` 按键。 + +.. figure:: ../../_static/get-started-eim-gui-uninstall-zh.png + :align: center + :alt: EIM 卸载 ESP-IDF + :figclass: align-center + + EIM 卸载 ESP-IDF + +使用 EIM CLI 卸载 ESP-IDF +========================= + +如需删除特定 ESP-IDF 版本，例如 v5.4.2，请在终端中运行以下命令： + +.. code-block:: bash + + eim remove v5.4.2 + +如需删除所有 ESP-IDF 版本，请在终端中运行以下命令： + +.. code-block:: bash + + eim purge diff --git a/docs/zh_CN/get-started/workflow-overview.rst b/docs/zh_CN/get-started/workflow-overview.rst new file mode 100644 index 00000000000..a64c356f2ef --- /dev/null +++ b/docs/zh_CN/get-started/workflow-overview.rst @@ -0,0 +1,51 @@ +工作流程概览 +============ + +:link_to_translation:`en:[English]` + +下图展示了如何搭建 ESP-IDF 的开发环境。无论是否从 IDE 开始，最终都将进入相同的开发工作流。 + +.. blockdiag:: /../_static/get-started-esp-idf-setup-zh.diag + :caption: ESP-IDF 环境搭建流程（点击放大） + :align: center + :scale: 60% + :alt: ESP-IDF 环境搭建流程 + +下图展示了如何使用 ESP-IDF 构建项目。 + +.. blockdiag:: /../_static/get-started-esp-idf-develop-zh.diag + :caption: ESP-IDF 开发工作流（点击放大） + :align: center + :scale: 60% + :alt: ESP-IDF 开发工作流 + + +相关文档 +-------- + +- 环境搭建流程 + + * 安装 IDE 和插件 + + + `Espressif-IDE > 准备工作 `_ + + `Espressif-IDE > 安装 `_ + + `VS Code 的 ESP-IDF 扩展 > 准备工作 `_ + + `VS Code 的 ESP-IDF 扩展 > 安装 ESP-IDF 和工具 `_ + + * 安装 EIM 依赖包、EIM，然后使用 EIM 安装 ESP-IDF + + + :doc:`windows-setup` + + :doc:`linux-setup` + + :doc:`macos-setup` + +- 开发工作流 + + * IDE + + + `Espressif-IDE > 启动项目 `_ + + `VS Code 的 ESP-IDF 扩展 > 启动项目 `_ + + * CLI + + + :doc:`windows-start-project` + + :doc:`linux-macos-start-project`