Getting started guides

CONTRIBUTING.rst

@@ -43,5 +43,13 @@ Legal Part
 
 Before a contribution can be accepted, you will need to sign our :doc:`contributor-agreement`. You will be prompted for this automatically as part of the Pull Request process.
 
+Related Documents
+-----------------
 
+.. toctree::
+    :maxdepth: 1
 
+    style-guide
+    documenting-code
+    ../api-reference/template
+    contributor-agreement

README.md

@@ -85,7 +85,7 @@ make -j5 flash monitor
 
 Once you've compiled your project, the "build" directory will contain a binary file with a name like "my_app.bin". This is an ESP32 image binary that can be loaded by the bootloader.
 
-A single ESP32's flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to offset 0x4000 in the flash.
+A single ESP32's flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to offset 0x8000 in the flash.
 
 Each entry in the partition table has a name (label), type (app, data, or something else), subtype and the offset in flash where the partition is loaded.
 

components/driver/include/driver/gpio.h

@@ -356,7 +356,7 @@ esp_err_t gpio_wakeup_disable(gpio_num_t gpio_num);
  * @param  handle Pointer to return handle. If non-NULL, a handle for the interrupt will be returned here.
  *
  * \verbatim embed:rst:leading-asterisk
- * To disable or remove the ISR, pass the returned handle to the :doc:`interrupt allocation functions </api/system/intr_alloc>`.
+ * To disable or remove the ISR, pass the returned handle to the :doc:`interrupt allocation functions </api-reference/system/intr_alloc>`.
  * \endverbatim
  *
  * @return

components/spi_flash/README.rst

@@ -5,7 +5,7 @@ Overview
 --------
 The spi_flash component contains APIs related to reading, writing, erasing,
 memory mapping data in the external SPI flash. It also has higher-level
-APIs which work with partitions defined in the :doc:`partition table </partition-tables>`.
+APIs which work with partitions defined in the :doc:`partition table </api-guides/partition-tables>`.
 
 Note that all the functionality is limited to the "main" SPI flash chip,
 the same SPI flash chip from which program runs. For ``spi_flash_*`` functions,
@@ -67,7 +67,7 @@ IRAM-Safe Interrupt Handlers
 If you have an interrupt handler that you want to execute even when a flash
 operation is in progress (for example, for low latency operations), set the
 ``ESP_INTR_FLAG_IRAM`` flag when the :doc:`interrupt handler is registered
-</api/system/intr_alloc>`.
+</api-reference/system/intr_alloc>`.
 
 You must ensure all data and functions accessed by these interrupt handlers are
 located in IRAM or DRAM. This includes any functions that the handler calls.
@@ -104,7 +104,7 @@ Partition table APIs
 
 ESP-IDF projects use a partition table to maintain information about various regions of
 SPI flash memory (bootloader, various application binaries, data, filesystems).
-More information about partition tables can be found :doc:`here </partition-tables>`.
+More information about partition tables can be found :doc:`here </api-guides/partition-tables>`.
 
 This component provides APIs to enumerate partitions found in the partition table
 and perform operations on them. These functions are declared in ``esp_partition.h``:

components/wear_levelling/README.rst

@@ -12,7 +12,7 @@ memory without user interaction.
 The wear_levelling component contains APIs related to reading, writing, erasing,
 memory mapping data in the external SPI flash through the partition component. It 
 also has higher-level APIs which work with FAT filesystem defined in 
-the :doc:`FAT filesystem </api/storage/fatfs>`.
+the :doc:`FAT filesystem </api-reference/storage/fatfs>`.
 
 The wear levelling component does not cache data in RAM. Write and erase functions 
 modify flash directly, and flash contents is consistent when the function returns.

docs/about.rst

@@ -0,0 +1,16 @@
+About
+=====
+
+This is documentation of `ESP-IDF <https://github.com/espressif/esp-idf>`_, the framework to develop applications for `ESP32 <https://espressif.com/en/products/hardware/esp32/overview>`_ chip by `Espressif <https://espressif.com>`_.
+
+The ESP32 is 2.4 GHz Wi-Fi and Bluetooth combo, 32 bit dual core chip with 600 DMIPS processing power.
+
+.. figure:: _static/about-doc.png
+    :align: center
+    :alt: Espressif IoT Integrated Development Framework
+    :figclass: align-center
+
+    Espressif IoT Integrated Development Framework
+
+The ESP-IDF, Espressif IoT Integrated Development Framework, provides toolchain, API, components and workflows to develop applications for ESP32 using Windows, Linux and Mac OS operating systems.
+

docs/api-guides/index.rst

@@ -0,0 +1,17 @@
+API Guides
+**********
+
+.. toctree::
+   :maxdepth: 1
+
+   General Notes <general-notes>
+   Build System <build-system>
+   Debugging <openocd>
+   ESP32 Core Dump <core_dump>
+   Partition Tables <partition-tables>
+   Flash Encryption <../security/flash-encryption>
+   Secure Boot <../security/secure-boot>
+   Deep Sleep Wake Stubs <deep-sleep-stub>
+   ULP Coprocessor <ulp>
+   Unit Testing <unit-tests>
+

docs/api-guides/partition-tables.rst

@@ -95,7 +95,7 @@ When type is "app", the subtype field can be specified as factory (0), ota_0 (0x
 
   - OTA never updates the factory partition.
   - If you want to conserve flash usage in an OTA project, you can remove the factory partition and use ota_0 instead.
-- ota_0 (0x10) ... ota_15 (0x1F) are the OTA app slots. Refer to the :doc:`OTA documentation <api/system/ota>` for more details, which then use the OTA data partition to configure which app slot the bootloader should boot. If using OTA, an application should have at least two OTA application slots (ota_0 & ota_1). Refer to the :doc:`OTA documentation <api/system/ota>` for more details.
+- ota_0 (0x10) ... ota_15 (0x1F) are the OTA app slots. Refer to the :doc:`OTA documentation <../api-reference/system/ota>` for more details, which then use the OTA data partition to configure which app slot the bootloader should boot. If using OTA, an application should have at least two OTA application slots (ota_0 & ota_1). Refer to the :doc:`OTA documentation <../api-reference/system/ota>` for more details.
 - test (0x2) is a reserved subtype for factory test procedures. It is not currently supported by the esp-idf bootloader.
 
 Data Subtypes
@@ -108,10 +108,10 @@ When type is "data", the subtype field can be specified as ota (0), phy (1), nvs
 
   - In the default configuration, the phy partition is not used and PHY initialisation data is compiled into the app itself. As such, this partition can be removed from the partition table to save space.
   - To load PHY data from this partition, run ``make menuconfig`` and enable "Component Config" -> "PHY" -> "Use a partition to store PHY init data". You will also need to flash your devices with phy init data as the esp-idf build system does not do this automatically.
-- nvs (2) is for the :doc:`Non-Volatile Storage (NVS) API <api/storage/nvs_flash>`.
+- nvs (2) is for the :doc:`Non-Volatile Storage (NVS) API <../api-reference/storage/nvs_flash>`.
 
   - NVS is used to store per-device PHY calibration data (different to initialisation data).
-  - NVS is used to store WiFi data if the :doc:`esp_wifi_set_storage(WIFI_STORAGE_FLASH) <api/wifi/esp_wifi>` initialisation function is used.
+  - NVS is used to store WiFi data if the :doc:`esp_wifi_set_storage(WIFI_STORAGE_FLASH) <../api-reference/wifi/esp_wifi>` initialisation function is used.
   - The NVS API can also be used for other application data.
   - It is strongly recommended that you include an NVS partition of at least 0x3000 bytes in your project.
   - If using NVS API to store a lot of data, increase the NVS partition size from the default 0x6000 bytes.

docs/api-guides/ulp_instruction_set.rst

@@ -1,5 +1,5 @@
 ULP coprocessor instruction set
-+++++++++++++++++++++++++++++++
+===============================
 
 This document provides details about the instructions used by ESP32 ULP coprocessor assembler.
 
@@ -242,7 +242,7 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
 
 
 **RSH** - Logical Shift Right
-----------------------------
+-----------------------------
 
 **Syntax**
    **RSH** *Rdst, Rsrc1, Rsrc2*

docs/api-guides/ulp_macros.rst

@@ -0,0 +1 @@
+.. include:: ../../components/ulp/README.rst

docs/api-reference/index.rst

@@ -0,0 +1,14 @@
+*************
+API Reference
+*************
+
+.. toctree::
+   :maxdepth: 2
+
+   Wi-Fi <wifi/index>
+   Bluetooth <bluetooth/index>
+   Ethernet <ethernet/index>
+   Peripherals <peripherals/index>
+   System <system/index>
+   Storage <storage/index>
+   Protocols <protocols/index>

docs/api-reference/peripherals/gpio.rst

@@ -4,12 +4,12 @@ GPIO & RTC GPIO
 Overview
 --------
 
-The ESP32 chip features 40 physical GPIO pads. Some GPIO pads cannot be used or do not have the corresponding pin on the chip package(refer to technical reference manual ). Each pad can be used as a general purpose I/O or can be connected to an internal peripheral signal.
+The ESP32 chip features 40 physical GPIO pads. Some GPIO pads cannot be used or do not have the corresponding pin on the chip package(refer to technical reference manual). Each pad can be used as a general purpose I/O or can be connected to an internal peripheral signal.
 
 - Note that GPIO6-11 are usually used for SPI flash.
 - GPIO34-39 can only be set as input mode and do not have software pullup or pulldown functions.
 
-There is also separate "RTC GPIO" support, which functions when GPIOs are routed to the "RTC" low-power and analog subsystem. These pin functions can be used when in deep sleep, when the :doc:`Ultra Low Power co-processor </ulp>` is running, or when analog functions such as ADC/DAC/etc are in use.
+There is also separate "RTC GPIO" support, which functions when GPIOs are routed to the "RTC" low-power and analog subsystem. These pin functions can be used when in deep sleep, when the :doc:`Ultra Low Power co-processor <../../api-guides/ulp>` is running, or when analog functions such as ADC/DAC/etc are in use.
 
 Application Example
 -------------------

docs/api-reference/storage/spi_flash.rst

@@ -3,8 +3,8 @@
 See also
 --------
 
-- :doc:`Partition Table documentation </partition-tables>`
-- :doc:`Over The Air Update (OTA) API </api/system/ota>` provides high-level API for updating app firmware stored in flash.
+- :doc:`Partition Table documentation <../../api-guides/partition-tables>`
+- :doc:`Over The Air Update (OTA) API <../system/ota>` provides high-level API for updating app firmware stored in flash.
 - :doc:`Non-Volatile Storage (NVS) API <nvs_flash>` provides a structured API for storing small items of data in SPI flash.
 
 API Reference

docs/api-reference/storage/wear-levelling.rst

@@ -3,8 +3,8 @@
 See also
 --------
 
-- :doc:`FAT Filesystem </partition-tables>`
-- :doc:`Partition Table documentation </partition-tables>`
+- :doc:`FAT Filesystem <../../api-guides/partition-tables>`
+- :doc:`Partition Table documentation <../../api-guides/partition-tables>`
 
 
 Application Example
@@ -14,7 +14,7 @@ An example which combines wear levelling driver with FATFS library is provided i
 wear levelling driver, mounts FATFS partition, and writes and reads data from it using POSIX and C library APIs. See README.md file in the example directory for more information.
 
 High level API Reference
--------------
+------------------------
 
 Header Files
 ^^^^^^^^^^^^
@@ -30,7 +30,7 @@ Functions
 .. doxygenfunction:: esp_vfs_fat_spiflash_unmount
 
 Mid level API Reference
--------------
+-----------------------
 
 Header Files
 ^^^^^^^^^^^^

docs/api-reference/system/ota.rst

@@ -7,7 +7,7 @@ OTA Process Overview
 The OTA update mechanism allows a device to update itself based on data received while the normal firmware is running
 (for example, over WiFi or Bluetooth.)
 
-OTA requires configuring the :doc:`Partition Table </partition-tables>` of the device with at least two "OTA app slot"
+OTA requires configuring the :doc:`Partition Table <../../api-guides/partition-tables>` of the device with at least two "OTA app slot"
 partitions (ie `ota_0` and `ota_1`) and an "OTA Data Partition".
 
 The OTA operation functions write a new app firmware image to whichever OTA app slot is not currently being used for
@@ -19,7 +19,7 @@ next boot.
 OTA Data Partition
 ^^^^^^^^^^^^^^^^^^
 
-An OTA data partition (type ``data``, subtype ``ota``) must be included in the :doc:`Partition Table </partition-tables>`
+An OTA data partition (type ``data``, subtype ``ota``) must be included in the :doc:`Partition Table <../../api-guides/partition-tables>`
 of any project which uses the OTA functions.
 
 For factory boot settings, the OTA data partition should contain no data (all bytes erased to 0xFF). In this case the
@@ -35,8 +35,8 @@ counter field is used to determine which sector was written more recently.
 See also
 --------
 
-* :doc:`Partition Table documentation </partition-tables>`
-* :doc:`Lower-Level SPI Flash/Partition API </api/storage/spi_flash>`
+* :doc:`Partition Table documentation <../../api-guides/partition-tables>`
+* :doc:`Lower-Level SPI Flash/Partition API <../storage/spi_flash>`
 
 Application Example
 -------------------

docs/api-reference/template.rst

@@ -1,5 +1,5 @@
-Template
-========
+API Documentation Template 
+==========================
 
 .. note::
 
@@ -7,7 +7,7 @@ Template
 
    1. Use this file as a template to document API.
    2. Change the file name to the name of the header file that represents documented API.
-   3. Include respective files with descriptions from the API folder using  ``..include::``
+   3. Include respective files with descriptions from the API folder using ``..include::``
 
      * README.rst
      * example.rst
@@ -69,7 +69,7 @@ API Reference
      See `Breathe documentation <https://breathe.readthedocs.io/en/latest/directives.html>`_ for additional information. 
 
    4. Once done remove superfluous headers.
-   5. When changes are committed and documentation is build, check how this section rendered. :doc:`Correct annotations <../documenting-code>` in respective header files, if required.
+   5. When changes are committed and documentation is build, check how this section rendered. :doc:`Correct annotations <../contribute/documenting-code>` in respective header files, if required.
 
 Header Files
 ^^^^^^^^^^^^