Prepare documentation for Espressif docs #1231
Conversation
|
Download the artifacts for this pull request: |
|
PTAL @f-hollow |
|
Pull request has been marked as |
brianignacio5
added
ongoing
There was a problem hiding this comment.
Great work, @brianignacio5 LGTM. I’ve added a few comments to improve the overall clarity and structure of the document.
docs_espressif/en/prerequisites.rst
Outdated
| =============================== | ||
| The minimum requirements for running the ESP-IDF Extension with the VSCode are below. | ||
|
|
||
| - `Visual Studio Code <https://code.visualstudio.com/>`_. | ||
|
|
||
| Linux / MacOS | ||
| ------------------------------- | ||
|
|
||
| - `Python 3.12 <https://www.python.org/downloads/>`_ and above. | ||
| - `Git <https://git-scm.com/downloads>`_. | ||
| - Install the following `ESP-IDF Prerequisites <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-setup.html#step-1-install-prerequisites>`_. | ||
|
|
||
| Next proceed to :ref:`Install ESP-IDF and Tools <installation>`. |
There was a problem hiding this comment.
Can we be specific about the Windows prerequisites as well?
There was a problem hiding this comment.
There is no prerequisite for Windows beside Visual Studio Code itself.
There was a problem hiding this comment.
I think we can still add Windows and just say "Nothing besides VS Code needed" or something like similar.
docs_espressif/en/installation.rst
Outdated
| Windows specific instructions here. | ||
| After installing Visual Studio Code you need to install the ESP-IDF extension for Visual Studio Code. | ||
|
|
||
| Open the **Extensions** view by clicking on the Extension icon in the Activity Bar on the side of Visual Studio Code or the **View: Extensions** command. |
There was a problem hiding this comment.
Is it possible to use an inline icon when referring to “clicking on the Extension icon” so that the user will be clear about which icon to look for?
docs_espressif/en/installation.rst
Outdated
| :kbd:`Ctrl+Shift+X` in Windows/Linux or :kbd:`Shift+⌘+X` in macOS. | ||
|
|
||
| Search for `ESP-IDF Extension <https://marketplace.visualstudio.com/items?itemName=espressif.esp-idf-extension>`_ from the list of extensions. | ||
|
|
||
| Install the extension. | ||
|
|
||
| In Visual Studio Code, select menu **View**, **Command Palette** and type **configure esp-idf extension**. | ||
|
|
||
| After, choose the **ESP-IDF: Configure ESP-IDF Extension** command. |
There was a problem hiding this comment.
For clarity to the user, better to use step-by-step instructions(Bullet Points).
docs_espressif/en/startproject.rst
Outdated
|
|
||
| .. image:: ../../media/tutorials/new_project/new_project_init.png | ||
|
|
||
| - Choose the project name, |
There was a problem hiding this comment.
We can remove the comma at the end of the sentence.
docs_espressif/en/startproject.rst
Outdated
|
|
||
| You can create a project using **ESP-IDF: New Project** or **ESP-IDF: Show Examples Projects** commands. | ||
|
|
||
| The first option is recommended as it allows you to configure the project while the second just create the project without configuration. |
There was a problem hiding this comment.
Having all the options with links would be helpful for the user before they delve into it.Something like below -
There are three ways one can get started with a project:
- ESP-IDF: New Project
- Using ESP-IDF Example Projects
- Opening an Existing ESP-IDF Project
docs_espressif/en/debugproject.rst
Outdated
| What happens in the background ? | ||
| ------------------------------------- | ||
|
|
||
| First OpenOCD server is launched in the background and the output is shown in menu **View** -> **Output** -> Select **ESP-IDF** from the dropdown. By default it will be launched using localhost, port ``4444`` for Telnet communication, port ``6666`` for TCL communication and port ``3333`` for gdb. The user can modify **openocd.tcl.host** and **openocd.tcl.port** configuration settings to modify these values. You can also set **idf.openOcdDebugLevel** to lower or increase (0-4) the messages from OpenOCD in the ESP-IDF output. |
There was a problem hiding this comment.
See if you can add a flow diagram or block diagram to make it easy to understand how an IDE and OpenOCD communicate.
docs_espressif/en/debugproject.rst
Outdated
| This adapter is a middle man between Visual Studio Code, configured toolchain GDB and OpenOCD server. You can see how `Espressif chips debugging works <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html#how-it-works>`_ and how Visual Studio Code use `Debug adapters <https://microsoft.github.io/debug-adapter-protocol/overview>`_ to communicate with many debug tools. | ||
|
|
||
| Using the Visual Studio Code debugger | ||
| ---------------------------------------- |
There was a problem hiding this comment.
Add a Table of Contents (ToC) for all the debugging features offered so that users can easily jump to them.
| @@ -1,2 +1,10 @@ | |||
| ESP-IDF Application Size Analysis | |||
| =================================== | |||
|
|
|||
| After building with select menu **View**, **Command Palette**, type **ESP-IDF: Build your Project** command; a the application size analysis task will be executed in a terminal showing the size analysis results. You can enable or disable this task being executed with **idf.enableSizeTaskAfterBuildTask** in your settings.json. | |||
There was a problem hiding this comment.
Before we delve into the technicalities, we could provide a 1-2 line introduction about this feature and how it benefits the user.
For example:
The ESP-IDF Application Size Analysis tool provides a detailed breakdown of your application’s memory usage, helping developers optimize storage allocation.
Follow the below instructions to view applciation size analysis from CLI:
- Navigate to View > Command Palette
- Type ESP-IDF: Build your Project command and this will be executed in a terminal showing the size analysis results
There was a problem hiding this comment.
It would be great if you could follow the same approach for all the features - give one or two lines of introduction and steps to configure.
|
|
||
| .. image:: ../../../media/tutorials/basic_use/size_terminal.png | ||
|
|
||
| For a visual output, Select menu **View**, **Command Palette**, type **ESP-IDF: Size Analysis of the Binaries** command to visually review the application size information. | ||
|
|
||
| .. image:: ../../../media/tutorials/basic_use/size.png |
There was a problem hiding this comment.
Please place the VSCode feature first before the CLI, as the user is already using VSCode visual features.
| @@ -0,0 +1,25 @@ | |||
| Hints Viewer | |||
There was a problem hiding this comment.
It would be great if you could add a Hints Viewer link in the Build project as a reference. Not only this, but all relevant links can be added there, and this is applicable to all features.
There was a problem hiding this comment.
I really like the new documentation, great job! I've left some changes requests and some suggestions.
A few general points:
- I think we should stick with a style of how we want to inform the users he needs to go through some steps, either by using '>', '-->' or by using words etc. I prefer the one with box style, red text and use of "-->" as I've explained in some comments where I've added a screenshot from esp-idf documentation.
- We should address the user in the same style, I think addressing him directly would be the best approach. I've left comments related to this where I've managed to catch it, but I think a search in the whole documentation for the word "user" would do a better job than relying on me catching all the places 😁
- I think we can group the following under a "Basic use" section, or something similar
- I've noticed in "Additional Features" section, we present almost every feature in a different style. As a solution I would propose to feed them to an AI and make it use a consistent style of presenting all the features and for the future we can try to stick to one way of documenting new features.
docs_espressif/en/installation.rst
Outdated
| Open the **Extensions** view by clicking on the Extension icon in the Activity Bar on the side of Visual Studio Code or the **View: Extensions** command. | ||
| :kbd:`Ctrl+Shift+X` in Windows/Linux or :kbd:`Shift+⌘+X` in macOS. | ||
|
|
||
| Search for `ESP-IDF Extension <https://marketplace.visualstudio.com/items?itemName=espressif.esp-idf-extension>`_ from the list of extensions. | ||
|
|
||
| Install the extension. | ||
|
|
||
| In Visual Studio Code, select menu **View**, **Command Palette** and type **configure esp-idf extension**. | ||
|
|
||
| After, choose the **ESP-IDF: Configure ESP-IDF Extension** command. |
There was a problem hiding this comment.
I agree with Kondal. I think we should keep the style similar to esp docs. Here is an example:
I would suggest to do the following style for all keyboard shortcuts as well (boxed with text color red)
docs_espressif/en/installation.rst
Outdated
| - **Espressif**: Faster speed in China using Espressif Download servers links. | ||
| - **Github**: Using github releases links. | ||
|
|
||
| Pick an ESP-IDF version to download or use the ``find ESP-IDF in your system`` option to search for existing ESP-IDF directory. |
There was a problem hiding this comment.
Here, we should use capital "F" for "find ESP-IDF in your system"
docs_espressif/en/installation.rst
Outdated
|
|
||
| .. image:: ../../media/tutorials/setup/select-esp-idf.png | ||
|
|
||
| Choose the location for ESP-IDF Tools ( ``IDF_TOOLS_PATH``) which is ``$HOME\.espressif`` on MacOS/Linux and ``%USERPROFILE%\.espressif`` on Windows by default. |
There was a problem hiding this comment.
For consistency I would recommend to keep a certain order for OS, so in this case I would put first the location of Windows value, then MacOS/Linux.
docs_espressif/en/installation.rst
Outdated
| After installing Visual Studio Code you need to install the ESP-IDF extension for Visual Studio Code. | ||
|
|
||
| Open the **Extensions** view by clicking on the Extension icon in the Activity Bar on the side of Visual Studio Code or the **View: Extensions** command. | ||
| :kbd:`Ctrl+Shift+X` in Windows/Linux or :kbd:`Shift+⌘+X` in macOS. |
There was a problem hiding this comment.
For consistency reasons, I would suggest to use the capitalized MacOS rather than macOS.
docs_espressif/en/installation.rst
Outdated
| * Make sure that ``IDF_TOOLS_PATH`` doesn't have any spaces to avoid any build issues. Also make sure that ``IDF_TOOLS_PATH`` is not the same directory as ``IDF_PATH``. | ||
|
|
||
| .. note:: | ||
| * For MacOS or Linux users, select the Python executable to use to create ESP-IDF python virtual environment. |
There was a problem hiding this comment.
Also, for consistency I think it's better to use either MacOS/Linux or MacOS or Linux throughout the documentation. I have a slight preference for using /.
I also think we should use capitalization for Python everywhere.
|
|
||
| **I try to build my project but there is an error and I don't know what is happening. What to do ?** | ||
|
|
||
| First of all, have you configure the IDE plugin/extension properly ? Make sure to review the documentation to :ref:`Install ESP-IDF and Tools <installation>`. |
There was a problem hiding this comment.
Should not have white space before ?
docs_espressif/en/faqs.rst
Outdated
|
|
||
| There was error in the setup or in your project code itself. Gather the :ref:`Troubleshooting documentation <troubleshooting>` and look for errors in these files. | ||
|
|
||
| Chances are that your issue have been posted before in the `ESP-IDF github repository <https://github.com/espressif/vscode-esp-idf-extension>`_ or `ESP-IDF forum <https://esp32.com>`_ . If not, you can open a new GitHub issue or open a topic in the forum. |
There was a problem hiding this comment.
Should not have white space before .
docs_espressif/en/faqs.rst
Outdated
|
|
||
| Chances are that your issue have been posted before in the `ESP-IDF github repository <https://github.com/espressif/vscode-esp-idf-extension>`_ or `ESP-IDF forum <https://esp32.com>`_ . If not, you can open a new GitHub issue or open a topic in the forum. | ||
|
|
||
| **How does a ESP-IDF project looks like ?** |
There was a problem hiding this comment.
Should not have white space before ?
docs_espressif/en/faqs.rst
Outdated
| - src2.c | ||
|
|
||
|
|
||
| **I tried flashing my project but I have an error similar to "Error: unable to open ftdi device with vid ". What to do ?** |
There was a problem hiding this comment.
Should not have white space before ?
docs_espressif/en/faqs.rst
Outdated
| **While trying to debug my project I have encountered an issue. What should I do?** | ||
|
|
||
| First review the `ESP-IDF JTAG Debugging documentation <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html#jtag-debugging-setup-openocd>`_ to understand how debugging works and the expected configuration of your device. | ||
| The debugger is connected to openOCD. Please take a look at `OpenOCD Troubleshooting FAQ <https://github.com/espressif/openocd-esp32/wiki/Troubleshooting-FAQ>`_ for any openOCD errors you might have encountered. |
There was a problem hiding this comment.
We should capitalise OpenOCD in this file
Description
Add RST files for Espressif documentation release. After finishing this PR we will have a new one for Chinese translation of these files.
Fix #1214
Type of change
Steps to test this pull request
Documentation change which will be available as preview documentation.
Expected behaviour:
Expected output:
How has this been tested?
Open preview documentation here To-DO add preview docs link
Checklist