From 9238ac9b33941a24a47741a1d3c3ab7fd36156f2 Mon Sep 17 00:00:00 2001 From: pedrominatel Date: Mon, 18 Sep 2023 19:02:17 +0100 Subject: [PATCH 01/21] Merge RTD to ESP-Docs --- docs/Makefile | 28 -------- docs/_static/arduino-esp32_versions.js | 16 +++++ docs/{source => }/_static/arduino-ide.png | Bin .../_static/arduino_i2c_master.png | Bin .../_static/arduino_i2c_slave.png | Bin docs/{source => }/_static/cross.png | Bin .../_static/esp32-c3_devkitM-1_pinlayout.png | Bin .../_static/esp32-s2_saola1_pinlayout.png | Bin .../_static/esp32_devkitC_pinlayout.png | Bin .../_static/external_library_test_pr.png | Bin .../external_library_test_schedule.png | Bin docs/{source => }/_static/gpio_output.png | Bin docs/{source => }/_static/gpio_pullup.png | Bin docs/{source => }/_static/green_checkmark.png | Bin .../install_guide_boards_manager_esp32.png | Bin .../install_guide_boards_manager_url.png | Bin .../_static/install_guide_preferences.png | Bin docs/{source => }/_static/logo_arduino.png | Bin docs/{source => }/_static/logo_espressif.png | Bin docs/{source => }/_static/logo_linux.png | Bin docs/{source => }/_static/logo_macos.png | Bin docs/{source => }/_static/logo_pio.png | Bin docs/{source => }/_static/logo_windows.png | Bin docs/{source => }/_static/ota_esp32_login.png | Bin .../{source => }/_static/ota_esp32_upload.png | Bin .../_static/ota_esp32_verbose.png | Bin .../_static/ota_export_to_binary.png | Bin docs/{source => }/_static/soc-module.png | Bin .../tutorials/basic/tutorial_basic_ide.png | Bin .../tutorial_peripheral_diagram.png | Bin docs/{source => }/_static/usb_msc_drive.png | Bin docs/{source => }/_static/warning.png | Bin docs/{source => }/_static/wifi_esp32_ap.png | Bin docs/{source => }/_static/wifi_esp32_sta.png | Bin docs/{source => }/_static/win-gui-1.png | Bin docs/{source => }/_static/win-gui-2.png | Bin docs/{source => }/_static/win-gui-3.png | Bin docs/{source => }/_static/win-gui-4.png | Bin docs/{source => }/_static/win-gui-5.png | Bin .../{source => }/_static/win-gui-update-1.png | Bin .../{source => }/_static/win-gui-update-2.png | Bin docs/conf_common.py | 30 ++++++++ docs/{source => en}/advanced_utils.rst | 0 docs/{source => en}/api/adc.rst | 0 docs/{source => en}/api/ble.rst | 0 docs/{source => en}/api/bluetooth.rst | 0 docs/{source => en}/api/dac.rst | 0 docs/{source => en}/api/deepsleep.rst | 0 docs/{source => en}/api/espnow.rst | 0 docs/{source => en}/api/ethernet.rst | 0 docs/{source => en}/api/gpio.rst | 0 docs/{source => en}/api/hall_sensor.rst | 0 docs/{source => en}/api/i2c.rst | 4 +- docs/{source => en}/api/i2s.rst | 0 docs/{source => en}/api/insights.rst | 0 docs/{source => en}/api/ledc.rst | 0 docs/{source => en}/api/preferences.rst | 0 docs/{source => en}/api/pulse_counter.rst | 0 docs/{source => en}/api/rainmaker.rst | 0 docs/{source => en}/api/reset_reason.rst | 0 docs/{source => en}/api/rmt.rst | 0 docs/{source => en}/api/sdio.rst | 0 docs/{source => en}/api/sdmmc.rst | 0 docs/{source => en}/api/sigmadelta.rst | 0 docs/{source => en}/api/spi.rst | 0 docs/{source => en}/api/timer.rst | 0 docs/{source => en}/api/touch.rst | 0 docs/{source => en}/api/usb.rst | 0 docs/{source => en}/api/usb_cdc.rst | 0 docs/{source => en}/api/usb_msc.rst | 0 docs/{source => en}/api/wifi.rst | 4 +- .../boards/ESP32-C3-DevKitM-1.rst | 2 +- .../{source => en}/boards/ESP32-DevKitC-1.rst | 2 +- .../boards/ESP32-S2-Saola-1.rst | 2 +- docs/{source => en}/boards/boards.rst | 4 +- docs/{source => en}/boards/generic.rst | 0 docs/{source => en}/common/datasheet.inc | 0 docs/en/conf.py | 25 +++++++ docs/{source => en}/contributing.rst | 0 docs/{source => en}/esp-idf_component.rst | 0 .../external_libraries_test.rst | 10 +-- docs/{source => en}/faq.rst | 0 docs/{source => en}/getting_started.rst | 10 +-- docs/{source => en}/guides/core_debug.rst | 0 .../guides/docs_contributing.rst | 2 +- docs/{source => en}/guides/guides.rst | 0 docs/{source => en}/guides/tools_menu.rst | 2 +- docs/{source => en}/index.rst | 0 docs/{source => en}/installing.rst | 30 ++++---- docs/{source => en}/lib_builder.rst | 0 docs/{source => en}/libraries.rst | 0 docs/{source => en}/make.rst | 0 docs/{source => en}/ota_web_update.rst | 8 +-- docs/{source => en}/troubleshooting.rst | 0 docs/{source => en}/tutorials/basic.rst | 2 +- docs/{source => en}/tutorials/blink.rst | 0 .../tutorials/cdc_dfu_flash.rst | 0 docs/{source => en}/tutorials/io_mux.rst | 2 +- .../tutorials/partition_table.rst | 0 docs/{source => en}/tutorials/preferences.rst | 0 docs/{source => en}/tutorials/tutorials.rst | 0 docs/make.bat | 35 --------- docs/requirements.txt | 7 +- docs/source/conf.py | 68 ------------------ 104 files changed, 115 insertions(+), 178 deletions(-) delete mode 100644 docs/Makefile create mode 100644 docs/_static/arduino-esp32_versions.js rename docs/{source => }/_static/arduino-ide.png (100%) rename docs/{source => }/_static/arduino_i2c_master.png (100%) rename docs/{source => }/_static/arduino_i2c_slave.png (100%) rename docs/{source => }/_static/cross.png (100%) rename docs/{source => }/_static/esp32-c3_devkitM-1_pinlayout.png (100%) rename docs/{source => }/_static/esp32-s2_saola1_pinlayout.png (100%) rename docs/{source => }/_static/esp32_devkitC_pinlayout.png (100%) rename docs/{source => }/_static/external_library_test_pr.png (100%) rename docs/{source => }/_static/external_library_test_schedule.png (100%) rename docs/{source => }/_static/gpio_output.png (100%) rename docs/{source => }/_static/gpio_pullup.png (100%) rename docs/{source => }/_static/green_checkmark.png (100%) rename docs/{source => }/_static/install_guide_boards_manager_esp32.png (100%) rename docs/{source => }/_static/install_guide_boards_manager_url.png (100%) rename docs/{source => }/_static/install_guide_preferences.png (100%) rename docs/{source => }/_static/logo_arduino.png (100%) rename docs/{source => }/_static/logo_espressif.png (100%) rename docs/{source => }/_static/logo_linux.png (100%) rename docs/{source => }/_static/logo_macos.png (100%) rename docs/{source => }/_static/logo_pio.png (100%) rename docs/{source => }/_static/logo_windows.png (100%) rename docs/{source => }/_static/ota_esp32_login.png (100%) rename docs/{source => }/_static/ota_esp32_upload.png (100%) rename docs/{source => }/_static/ota_esp32_verbose.png (100%) rename docs/{source => }/_static/ota_export_to_binary.png (100%) rename docs/{source => }/_static/soc-module.png (100%) rename docs/{source => }/_static/tutorials/basic/tutorial_basic_ide.png (100%) rename docs/{source => }/_static/tutorials/peripherals/tutorial_peripheral_diagram.png (100%) rename docs/{source => }/_static/usb_msc_drive.png (100%) rename docs/{source => }/_static/warning.png (100%) rename docs/{source => }/_static/wifi_esp32_ap.png (100%) rename docs/{source => }/_static/wifi_esp32_sta.png (100%) rename docs/{source => }/_static/win-gui-1.png (100%) rename docs/{source => }/_static/win-gui-2.png (100%) rename docs/{source => }/_static/win-gui-3.png (100%) rename docs/{source => }/_static/win-gui-4.png (100%) rename docs/{source => }/_static/win-gui-5.png (100%) rename docs/{source => }/_static/win-gui-update-1.png (100%) rename docs/{source => }/_static/win-gui-update-2.png (100%) create mode 100644 docs/conf_common.py rename docs/{source => en}/advanced_utils.rst (100%) rename docs/{source => en}/api/adc.rst (100%) rename docs/{source => en}/api/ble.rst (100%) rename docs/{source => en}/api/bluetooth.rst (100%) rename docs/{source => en}/api/dac.rst (100%) rename docs/{source => en}/api/deepsleep.rst (100%) rename docs/{source => en}/api/espnow.rst (100%) rename docs/{source => en}/api/ethernet.rst (100%) rename docs/{source => en}/api/gpio.rst (100%) rename docs/{source => en}/api/hall_sensor.rst (100%) rename docs/{source => en}/api/i2c.rst (99%) rename docs/{source => en}/api/i2s.rst (100%) rename docs/{source => en}/api/insights.rst (100%) rename docs/{source => en}/api/ledc.rst (100%) rename docs/{source => en}/api/preferences.rst (100%) rename docs/{source => en}/api/pulse_counter.rst (100%) rename docs/{source => en}/api/rainmaker.rst (100%) rename docs/{source => en}/api/reset_reason.rst (100%) rename docs/{source => en}/api/rmt.rst (100%) rename docs/{source => en}/api/sdio.rst (100%) rename docs/{source => en}/api/sdmmc.rst (100%) rename docs/{source => en}/api/sigmadelta.rst (100%) rename docs/{source => en}/api/spi.rst (100%) rename docs/{source => en}/api/timer.rst (100%) rename docs/{source => en}/api/touch.rst (100%) rename docs/{source => en}/api/usb.rst (100%) rename docs/{source => en}/api/usb_cdc.rst (100%) rename docs/{source => en}/api/usb_msc.rst (100%) rename docs/{source => en}/api/wifi.rst (99%) rename docs/{source => en}/boards/ESP32-C3-DevKitM-1.rst (98%) rename docs/{source => en}/boards/ESP32-DevKitC-1.rst (98%) rename docs/{source => en}/boards/ESP32-S2-Saola-1.rst (98%) rename docs/{source => en}/boards/boards.rst (97%) rename docs/{source => en}/boards/generic.rst (100%) rename docs/{source => en}/common/datasheet.inc (100%) create mode 100644 docs/en/conf.py rename docs/{source => en}/contributing.rst (100%) rename docs/{source => en}/esp-idf_component.rst (100%) rename docs/{source => en}/external_libraries_test.rst (94%) rename docs/{source => en}/faq.rst (100%) rename docs/{source => en}/getting_started.rst (95%) rename docs/{source => en}/guides/core_debug.rst (100%) rename docs/{source => en}/guides/docs_contributing.rst (99%) rename docs/{source => en}/guides/guides.rst (100%) rename docs/{source => en}/guides/tools_menu.rst (99%) rename docs/{source => en}/index.rst (100%) rename docs/{source => en}/installing.rst (94%) rename docs/{source => en}/lib_builder.rst (100%) rename docs/{source => en}/libraries.rst (100%) rename docs/{source => en}/make.rst (100%) rename docs/{source => en}/ota_web_update.rst (93%) rename docs/{source => en}/troubleshooting.rst (100%) rename docs/{source => en}/tutorials/basic.rst (97%) rename docs/{source => en}/tutorials/blink.rst (100%) rename docs/{source => en}/tutorials/cdc_dfu_flash.rst (100%) rename docs/{source => en}/tutorials/io_mux.rst (98%) rename docs/{source => en}/tutorials/partition_table.rst (100%) rename docs/{source => en}/tutorials/preferences.rst (100%) rename docs/{source => en}/tutorials/tutorials.rst (100%) delete mode 100644 docs/make.bat delete mode 100644 docs/source/conf.py diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index ba5447de969..00000000000 --- a/docs/Makefile +++ /dev/null @@ -1,28 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build - -LINKCHECKDIR = build/linkcheck - -.PHONY: checklinks - checklinks: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(LINKCHECKDIR) - @echo - @echo "Check finished. Report is in $(LINKCHECKDIR)." - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_static/arduino-esp32_versions.js b/docs/_static/arduino-esp32_versions.js new file mode 100644 index 00000000000..b4b772d5c45 --- /dev/null +++ b/docs/_static/arduino-esp32_versions.js @@ -0,0 +1,16 @@ +var DOCUMENTATION_VERSIONS = { + DEFAULTS: { has_targets: false, + supported_targets: [ "esp32" ] + }, + VERSIONS: [ + { name: "latest", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3", "esp32h2", "esp32c6" ] }, + ], + IDF_TARGETS: [ + { text: "ESP32", value: "esp32"}, + { text: "ESP32-S2", value: "esp32s2"}, + { text: "ESP32-S3", value: "esp32s3"}, + { text: "ESP32-C3", value: "esp32c3"}, + { text: "ESP32-H2", value: "esp32h2"}, + { text: "ESP32C6", value: "esp32c6"}, + ] +}; \ No newline at end of file diff --git a/docs/source/_static/arduino-ide.png b/docs/_static/arduino-ide.png similarity index 100% rename from docs/source/_static/arduino-ide.png rename to docs/_static/arduino-ide.png diff --git a/docs/source/_static/arduino_i2c_master.png b/docs/_static/arduino_i2c_master.png similarity index 100% rename from docs/source/_static/arduino_i2c_master.png rename to docs/_static/arduino_i2c_master.png diff --git a/docs/source/_static/arduino_i2c_slave.png b/docs/_static/arduino_i2c_slave.png similarity index 100% rename from docs/source/_static/arduino_i2c_slave.png rename to docs/_static/arduino_i2c_slave.png diff --git a/docs/source/_static/cross.png b/docs/_static/cross.png similarity index 100% rename from docs/source/_static/cross.png rename to docs/_static/cross.png diff --git a/docs/source/_static/esp32-c3_devkitM-1_pinlayout.png b/docs/_static/esp32-c3_devkitM-1_pinlayout.png similarity index 100% rename from docs/source/_static/esp32-c3_devkitM-1_pinlayout.png rename to docs/_static/esp32-c3_devkitM-1_pinlayout.png diff --git a/docs/source/_static/esp32-s2_saola1_pinlayout.png b/docs/_static/esp32-s2_saola1_pinlayout.png similarity index 100% rename from docs/source/_static/esp32-s2_saola1_pinlayout.png rename to docs/_static/esp32-s2_saola1_pinlayout.png diff --git a/docs/source/_static/esp32_devkitC_pinlayout.png b/docs/_static/esp32_devkitC_pinlayout.png similarity index 100% rename from docs/source/_static/esp32_devkitC_pinlayout.png rename to docs/_static/esp32_devkitC_pinlayout.png diff --git a/docs/source/_static/external_library_test_pr.png b/docs/_static/external_library_test_pr.png similarity index 100% rename from docs/source/_static/external_library_test_pr.png rename to docs/_static/external_library_test_pr.png diff --git a/docs/source/_static/external_library_test_schedule.png b/docs/_static/external_library_test_schedule.png similarity index 100% rename from docs/source/_static/external_library_test_schedule.png rename to docs/_static/external_library_test_schedule.png diff --git a/docs/source/_static/gpio_output.png b/docs/_static/gpio_output.png similarity index 100% rename from docs/source/_static/gpio_output.png rename to docs/_static/gpio_output.png diff --git a/docs/source/_static/gpio_pullup.png b/docs/_static/gpio_pullup.png similarity index 100% rename from docs/source/_static/gpio_pullup.png rename to docs/_static/gpio_pullup.png diff --git a/docs/source/_static/green_checkmark.png b/docs/_static/green_checkmark.png similarity index 100% rename from docs/source/_static/green_checkmark.png rename to docs/_static/green_checkmark.png diff --git a/docs/source/_static/install_guide_boards_manager_esp32.png b/docs/_static/install_guide_boards_manager_esp32.png similarity index 100% rename from docs/source/_static/install_guide_boards_manager_esp32.png rename to docs/_static/install_guide_boards_manager_esp32.png diff --git a/docs/source/_static/install_guide_boards_manager_url.png b/docs/_static/install_guide_boards_manager_url.png similarity index 100% rename from docs/source/_static/install_guide_boards_manager_url.png rename to docs/_static/install_guide_boards_manager_url.png diff --git a/docs/source/_static/install_guide_preferences.png b/docs/_static/install_guide_preferences.png similarity index 100% rename from docs/source/_static/install_guide_preferences.png rename to docs/_static/install_guide_preferences.png diff --git a/docs/source/_static/logo_arduino.png b/docs/_static/logo_arduino.png similarity index 100% rename from docs/source/_static/logo_arduino.png rename to docs/_static/logo_arduino.png diff --git a/docs/source/_static/logo_espressif.png b/docs/_static/logo_espressif.png similarity index 100% rename from docs/source/_static/logo_espressif.png rename to docs/_static/logo_espressif.png diff --git a/docs/source/_static/logo_linux.png b/docs/_static/logo_linux.png similarity index 100% rename from docs/source/_static/logo_linux.png rename to docs/_static/logo_linux.png diff --git a/docs/source/_static/logo_macos.png b/docs/_static/logo_macos.png similarity index 100% rename from docs/source/_static/logo_macos.png rename to docs/_static/logo_macos.png diff --git a/docs/source/_static/logo_pio.png b/docs/_static/logo_pio.png similarity index 100% rename from docs/source/_static/logo_pio.png rename to docs/_static/logo_pio.png diff --git a/docs/source/_static/logo_windows.png b/docs/_static/logo_windows.png similarity index 100% rename from docs/source/_static/logo_windows.png rename to docs/_static/logo_windows.png diff --git a/docs/source/_static/ota_esp32_login.png b/docs/_static/ota_esp32_login.png similarity index 100% rename from docs/source/_static/ota_esp32_login.png rename to docs/_static/ota_esp32_login.png diff --git a/docs/source/_static/ota_esp32_upload.png b/docs/_static/ota_esp32_upload.png similarity index 100% rename from docs/source/_static/ota_esp32_upload.png rename to docs/_static/ota_esp32_upload.png diff --git a/docs/source/_static/ota_esp32_verbose.png b/docs/_static/ota_esp32_verbose.png similarity index 100% rename from docs/source/_static/ota_esp32_verbose.png rename to docs/_static/ota_esp32_verbose.png diff --git a/docs/source/_static/ota_export_to_binary.png b/docs/_static/ota_export_to_binary.png similarity index 100% rename from docs/source/_static/ota_export_to_binary.png rename to docs/_static/ota_export_to_binary.png diff --git a/docs/source/_static/soc-module.png b/docs/_static/soc-module.png similarity index 100% rename from docs/source/_static/soc-module.png rename to docs/_static/soc-module.png diff --git a/docs/source/_static/tutorials/basic/tutorial_basic_ide.png b/docs/_static/tutorials/basic/tutorial_basic_ide.png similarity index 100% rename from docs/source/_static/tutorials/basic/tutorial_basic_ide.png rename to docs/_static/tutorials/basic/tutorial_basic_ide.png diff --git a/docs/source/_static/tutorials/peripherals/tutorial_peripheral_diagram.png b/docs/_static/tutorials/peripherals/tutorial_peripheral_diagram.png similarity index 100% rename from docs/source/_static/tutorials/peripherals/tutorial_peripheral_diagram.png rename to docs/_static/tutorials/peripherals/tutorial_peripheral_diagram.png diff --git a/docs/source/_static/usb_msc_drive.png b/docs/_static/usb_msc_drive.png similarity index 100% rename from docs/source/_static/usb_msc_drive.png rename to docs/_static/usb_msc_drive.png diff --git a/docs/source/_static/warning.png b/docs/_static/warning.png similarity index 100% rename from docs/source/_static/warning.png rename to docs/_static/warning.png diff --git a/docs/source/_static/wifi_esp32_ap.png b/docs/_static/wifi_esp32_ap.png similarity index 100% rename from docs/source/_static/wifi_esp32_ap.png rename to docs/_static/wifi_esp32_ap.png diff --git a/docs/source/_static/wifi_esp32_sta.png b/docs/_static/wifi_esp32_sta.png similarity index 100% rename from docs/source/_static/wifi_esp32_sta.png rename to docs/_static/wifi_esp32_sta.png diff --git a/docs/source/_static/win-gui-1.png b/docs/_static/win-gui-1.png similarity index 100% rename from docs/source/_static/win-gui-1.png rename to docs/_static/win-gui-1.png diff --git a/docs/source/_static/win-gui-2.png b/docs/_static/win-gui-2.png similarity index 100% rename from docs/source/_static/win-gui-2.png rename to docs/_static/win-gui-2.png diff --git a/docs/source/_static/win-gui-3.png b/docs/_static/win-gui-3.png similarity index 100% rename from docs/source/_static/win-gui-3.png rename to docs/_static/win-gui-3.png diff --git a/docs/source/_static/win-gui-4.png b/docs/_static/win-gui-4.png similarity index 100% rename from docs/source/_static/win-gui-4.png rename to docs/_static/win-gui-4.png diff --git a/docs/source/_static/win-gui-5.png b/docs/_static/win-gui-5.png similarity index 100% rename from docs/source/_static/win-gui-5.png rename to docs/_static/win-gui-5.png diff --git a/docs/source/_static/win-gui-update-1.png b/docs/_static/win-gui-update-1.png similarity index 100% rename from docs/source/_static/win-gui-update-1.png rename to docs/_static/win-gui-update-1.png diff --git a/docs/source/_static/win-gui-update-2.png b/docs/_static/win-gui-update-2.png similarity index 100% rename from docs/source/_static/win-gui-update-2.png rename to docs/_static/win-gui-update-2.png diff --git a/docs/conf_common.py b/docs/conf_common.py new file mode 100644 index 00000000000..9aab8d4a224 --- /dev/null +++ b/docs/conf_common.py @@ -0,0 +1,30 @@ +# --------------------------------------------------------------- + +from esp_docs.conf_docs import * # noqa: F403,F401 + +languages = ["en"] + +# link roles config +github_repo = "espressif/arduino-esp32" + +# context used by sphinx_idf_theme +html_context["github_user"] = "espressif" +html_context["github_repo"] = "arduino-esp32" + +html_static_path = ["../_static"] + +# Conditional content + +extensions += ['sphinx_copybutton', + 'sphinx_tabs.tabs', + 'esp_docs.esp_extensions.dummy_build_system', + ] + +ESP32_DOCS = [ + "index.rst", +] + +# Extra options required by sphinx_idf_theme +project_slug = "arduino-esp32" + +versions_url = "./_static/arduino-esp32_versions.js" diff --git a/docs/source/advanced_utils.rst b/docs/en/advanced_utils.rst similarity index 100% rename from docs/source/advanced_utils.rst rename to docs/en/advanced_utils.rst diff --git a/docs/source/api/adc.rst b/docs/en/api/adc.rst similarity index 100% rename from docs/source/api/adc.rst rename to docs/en/api/adc.rst diff --git a/docs/source/api/ble.rst b/docs/en/api/ble.rst similarity index 100% rename from docs/source/api/ble.rst rename to docs/en/api/ble.rst diff --git a/docs/source/api/bluetooth.rst b/docs/en/api/bluetooth.rst similarity index 100% rename from docs/source/api/bluetooth.rst rename to docs/en/api/bluetooth.rst diff --git a/docs/source/api/dac.rst b/docs/en/api/dac.rst similarity index 100% rename from docs/source/api/dac.rst rename to docs/en/api/dac.rst diff --git a/docs/source/api/deepsleep.rst b/docs/en/api/deepsleep.rst similarity index 100% rename from docs/source/api/deepsleep.rst rename to docs/en/api/deepsleep.rst diff --git a/docs/source/api/espnow.rst b/docs/en/api/espnow.rst similarity index 100% rename from docs/source/api/espnow.rst rename to docs/en/api/espnow.rst diff --git a/docs/source/api/ethernet.rst b/docs/en/api/ethernet.rst similarity index 100% rename from docs/source/api/ethernet.rst rename to docs/en/api/ethernet.rst diff --git a/docs/source/api/gpio.rst b/docs/en/api/gpio.rst similarity index 100% rename from docs/source/api/gpio.rst rename to docs/en/api/gpio.rst diff --git a/docs/source/api/hall_sensor.rst b/docs/en/api/hall_sensor.rst similarity index 100% rename from docs/source/api/hall_sensor.rst rename to docs/en/api/hall_sensor.rst diff --git a/docs/source/api/i2c.rst b/docs/en/api/i2c.rst similarity index 99% rename from docs/source/api/i2c.rst rename to docs/en/api/i2c.rst index f53d8f27a3c..31a07f88046 100644 --- a/docs/source/api/i2c.rst +++ b/docs/en/api/i2c.rst @@ -19,7 +19,7 @@ The I2C can be used in two different modes: * **I2C Master Mode** * In this mode, the ESP32 generates the clock signal and initiates the communication with the slave device. -.. figure:: ../_static/arduino_i2c_master.png +.. figure:: ../../_static/arduino_i2c_master.png :align: center :width: 720 :figclass: align-center @@ -27,7 +27,7 @@ The I2C can be used in two different modes: * **I2C Slave Mode** * The slave mode, the clock is generated by the master device and responds to the master if the destination address is the same as the destination. -.. figure:: ../_static/arduino_i2c_slave.png +.. figure:: ../../_static/arduino_i2c_slave.png :align: center :width: 520 :figclass: align-center diff --git a/docs/source/api/i2s.rst b/docs/en/api/i2s.rst similarity index 100% rename from docs/source/api/i2s.rst rename to docs/en/api/i2s.rst diff --git a/docs/source/api/insights.rst b/docs/en/api/insights.rst similarity index 100% rename from docs/source/api/insights.rst rename to docs/en/api/insights.rst diff --git a/docs/source/api/ledc.rst b/docs/en/api/ledc.rst similarity index 100% rename from docs/source/api/ledc.rst rename to docs/en/api/ledc.rst diff --git a/docs/source/api/preferences.rst b/docs/en/api/preferences.rst similarity index 100% rename from docs/source/api/preferences.rst rename to docs/en/api/preferences.rst diff --git a/docs/source/api/pulse_counter.rst b/docs/en/api/pulse_counter.rst similarity index 100% rename from docs/source/api/pulse_counter.rst rename to docs/en/api/pulse_counter.rst diff --git a/docs/source/api/rainmaker.rst b/docs/en/api/rainmaker.rst similarity index 100% rename from docs/source/api/rainmaker.rst rename to docs/en/api/rainmaker.rst diff --git a/docs/source/api/reset_reason.rst b/docs/en/api/reset_reason.rst similarity index 100% rename from docs/source/api/reset_reason.rst rename to docs/en/api/reset_reason.rst diff --git a/docs/source/api/rmt.rst b/docs/en/api/rmt.rst similarity index 100% rename from docs/source/api/rmt.rst rename to docs/en/api/rmt.rst diff --git a/docs/source/api/sdio.rst b/docs/en/api/sdio.rst similarity index 100% rename from docs/source/api/sdio.rst rename to docs/en/api/sdio.rst diff --git a/docs/source/api/sdmmc.rst b/docs/en/api/sdmmc.rst similarity index 100% rename from docs/source/api/sdmmc.rst rename to docs/en/api/sdmmc.rst diff --git a/docs/source/api/sigmadelta.rst b/docs/en/api/sigmadelta.rst similarity index 100% rename from docs/source/api/sigmadelta.rst rename to docs/en/api/sigmadelta.rst diff --git a/docs/source/api/spi.rst b/docs/en/api/spi.rst similarity index 100% rename from docs/source/api/spi.rst rename to docs/en/api/spi.rst diff --git a/docs/source/api/timer.rst b/docs/en/api/timer.rst similarity index 100% rename from docs/source/api/timer.rst rename to docs/en/api/timer.rst diff --git a/docs/source/api/touch.rst b/docs/en/api/touch.rst similarity index 100% rename from docs/source/api/touch.rst rename to docs/en/api/touch.rst diff --git a/docs/source/api/usb.rst b/docs/en/api/usb.rst similarity index 100% rename from docs/source/api/usb.rst rename to docs/en/api/usb.rst diff --git a/docs/source/api/usb_cdc.rst b/docs/en/api/usb_cdc.rst similarity index 100% rename from docs/source/api/usb_cdc.rst rename to docs/en/api/usb_cdc.rst diff --git a/docs/source/api/usb_msc.rst b/docs/en/api/usb_msc.rst similarity index 100% rename from docs/source/api/usb_msc.rst rename to docs/en/api/usb_msc.rst diff --git a/docs/source/api/wifi.rst b/docs/en/api/wifi.rst similarity index 99% rename from docs/source/api/wifi.rst rename to docs/en/api/wifi.rst index eb32b4af53e..d5632ae7717 100644 --- a/docs/source/api/wifi.rst +++ b/docs/en/api/wifi.rst @@ -21,7 +21,7 @@ Working as AP In this mode, the ESP32 is configured as an Access Point (AP) and it's capable of receiving incoming connections from other devices (stations) by providing a Wi-Fi network. -.. figure:: ../_static/wifi_esp32_ap.png +.. figure:: ../../_static/wifi_esp32_ap.png :align: center :width: 520 :figclass: align-center @@ -33,7 +33,7 @@ Working as STA The STA mode is used to connect the ESP32 to a Wi-Fi network, provided by an Access Point. -.. figure:: ../_static/wifi_esp32_sta.png +.. figure:: ../../_static/wifi_esp32_sta.png :align: center :width: 520 :figclass: align-center diff --git a/docs/source/boards/ESP32-C3-DevKitM-1.rst b/docs/en/boards/ESP32-C3-DevKitM-1.rst similarity index 98% rename from docs/source/boards/ESP32-C3-DevKitM-1.rst rename to docs/en/boards/ESP32-C3-DevKitM-1.rst index 7ce9475d69b..11e6e45d55f 100644 --- a/docs/source/boards/ESP32-C3-DevKitM-1.rst +++ b/docs/en/boards/ESP32-C3-DevKitM-1.rst @@ -88,7 +88,7 @@ No. Name Type [1]_ Function Pin Layout ---------- -.. figure:: ../_static/esp32-c3_devkitM-1_pinlayout.png +.. figure:: ../../_static/esp32-c3_devkitM-1_pinlayout.png :align: center :width: 600 :alt: ESP32-C3-DevKitM-1 (click to enlarge) diff --git a/docs/source/boards/ESP32-DevKitC-1.rst b/docs/en/boards/ESP32-DevKitC-1.rst similarity index 98% rename from docs/source/boards/ESP32-DevKitC-1.rst rename to docs/en/boards/ESP32-DevKitC-1.rst index dcd5632eab7..4bb86696227 100644 --- a/docs/source/boards/ESP32-DevKitC-1.rst +++ b/docs/en/boards/ESP32-DevKitC-1.rst @@ -96,7 +96,7 @@ No. Name Type Function Pin Layout ---------- -.. figure:: ../_static/esp32_devkitC_pinlayout.png +.. figure:: ../../_static/esp32_devkitC_pinlayout.png :align: center :width: 600 :alt: ESP32-DevKitC-1 (click to enlarge) diff --git a/docs/source/boards/ESP32-S2-Saola-1.rst b/docs/en/boards/ESP32-S2-Saola-1.rst similarity index 98% rename from docs/source/boards/ESP32-S2-Saola-1.rst rename to docs/en/boards/ESP32-S2-Saola-1.rst index fd41772c234..1a06a6d87bb 100644 --- a/docs/source/boards/ESP32-S2-Saola-1.rst +++ b/docs/en/boards/ESP32-S2-Saola-1.rst @@ -100,7 +100,7 @@ No. Name Type Function Pin Layout ---------- -.. figure:: ../_static/esp32-s2_saola1_pinlayout.png +.. figure:: ../../_static/esp32-s2_saola1_pinlayout.png :align: center :width: 600 :alt: ESP32-S2-Saola-1 (click to enlarge) diff --git a/docs/source/boards/boards.rst b/docs/en/boards/boards.rst similarity index 97% rename from docs/source/boards/boards.rst rename to docs/en/boards/boards.rst index 344e9c1c9da..9a1d2217dac 100644 --- a/docs/source/boards/boards.rst +++ b/docs/en/boards/boards.rst @@ -28,7 +28,7 @@ For each family, we have SoC variants with some differentiation. The differences The modules use the SoC internally, including the external flash, PSRAM (in some models) and other essential electronic components. Essentially, all modules from the same family use the same SoC. -.. figure:: ../_static/soc-module.png +.. figure:: ../../_static/soc-module.png :align: center :width: 250 :alt: ESP32 SoC and Module (click to enlarge) @@ -58,7 +58,7 @@ Before buying: Keep in mind that for some "must have" features when choosing the Espressif --------- -.. figure:: ../_static/logo_espressif.png +.. figure:: ../../_static/logo_espressif.png :align: center :width: 250 :alt: Espressif Logo diff --git a/docs/source/boards/generic.rst b/docs/en/boards/generic.rst similarity index 100% rename from docs/source/boards/generic.rst rename to docs/en/boards/generic.rst diff --git a/docs/source/common/datasheet.inc b/docs/en/common/datasheet.inc similarity index 100% rename from docs/source/common/datasheet.inc rename to docs/en/common/datasheet.inc diff --git a/docs/en/conf.py b/docs/en/conf.py new file mode 100644 index 00000000000..ea8f20e4604 --- /dev/null +++ b/docs/en/conf.py @@ -0,0 +1,25 @@ +# -*- coding: utf-8 -*- +# +# English Language RTD & Sphinx config file +# +# Uses ../conf_common.py for most non-language-specific settings. + +# Importing conf_common adds all the non-language-specific +# parts to this conf module + +try: + from conf_common import * # noqa: F403,F401 +except ImportError: + import os + import sys + sys.path.insert(0, os.path.abspath('../')) + from conf_common import * # noqa: F403,F401 + +# General information about the project. +project = u'Arduino ESP32' +copyright = u'2016 - 2023, Espressif Systems (Shanghai) Co., Ltd' +pdf_title = u'Arduino ESP32 Documentation Guide' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +language = 'en' \ No newline at end of file diff --git a/docs/source/contributing.rst b/docs/en/contributing.rst similarity index 100% rename from docs/source/contributing.rst rename to docs/en/contributing.rst diff --git a/docs/source/esp-idf_component.rst b/docs/en/esp-idf_component.rst similarity index 100% rename from docs/source/esp-idf_component.rst rename to docs/en/esp-idf_component.rst diff --git a/docs/source/external_libraries_test.rst b/docs/en/external_libraries_test.rst similarity index 94% rename from docs/source/external_libraries_test.rst rename to docs/en/external_libraries_test.rst index 2064987df07..0d7da671cd2 100644 --- a/docs/source/external_libraries_test.rst +++ b/docs/en/external_libraries_test.rst @@ -104,7 +104,7 @@ You can check the results in `LIBRARIES_TEST.md`_. The results file example: -.. image:: _static/external_library_test_schedule.png +.. image:: ../_static/external_library_test_schedule.png :width: 600 Pull Request test result @@ -113,18 +113,18 @@ Pull Request test result If the test run on Pull Request, it will compile all libraries and sketches 2 times (before/after changes in PR) to see, if the PR is breaking/fixing libraries. In the table the results are in order ``BEFORE -> AFTER``. -.. image:: _static/external_library_test_pr.png +.. image:: ../_static/external_library_test_pr.png :width: 600 -.. |success| image:: _static/green_checkmark.png +.. |success| image:: ../_static/green_checkmark.png :height: 2ex :class: no-scaled-link -.. |warning| image:: _static/warning.png +.. |warning| image:: ../_static/warning.png :height: 2ex :class: no-scaled-link -.. |fail| image:: _static/cross.png +.. |fail| image:: ../_static/cross.png :height: 2ex :class: no-scaled-link diff --git a/docs/source/faq.rst b/docs/en/faq.rst similarity index 100% rename from docs/source/faq.rst rename to docs/en/faq.rst diff --git a/docs/source/getting_started.rst b/docs/en/getting_started.rst similarity index 95% rename from docs/source/getting_started.rst rename to docs/en/getting_started.rst index 4093b415c07..6b2d4aca959 100644 --- a/docs/source/getting_started.rst +++ b/docs/en/getting_started.rst @@ -62,9 +62,9 @@ Supported Operating Systems | Windows | Linux | macOS | +-------------------+-------------------+-------------------+ -.. |windows-logo| image:: _static/logo_windows.png -.. |linux-logo| image:: _static/logo_linux.png -.. |macos-logo| image:: _static/logo_macos.png +.. |windows-logo| image:: ../_static/logo_windows.png +.. |linux-logo| image:: ../_static/logo_linux.png +.. |macos-logo| image:: ../_static/logo_macos.png Supported IDEs --------------------------- @@ -77,8 +77,8 @@ Here is the list of supported IDE for Arduino ESP32 support integration. | Arduino IDE | PlatformIO | +-------------------+-------------------+ -.. |arduino-logo| image:: _static/logo_arduino.png -.. |pio-logo| image:: _static/logo_pio.png +.. |arduino-logo| image:: ../_static/logo_arduino.png +.. |pio-logo| image:: ../_static/logo_pio.png See `Installing Guides `_ for more details on how to install the Arduino ESP32 support. diff --git a/docs/source/guides/core_debug.rst b/docs/en/guides/core_debug.rst similarity index 100% rename from docs/source/guides/core_debug.rst rename to docs/en/guides/core_debug.rst diff --git a/docs/source/guides/docs_contributing.rst b/docs/en/guides/docs_contributing.rst similarity index 99% rename from docs/source/guides/docs_contributing.rst rename to docs/en/guides/docs_contributing.rst index be5a54e4b37..3bcffc0bf74 100644 --- a/docs/source/guides/docs_contributing.rst +++ b/docs/en/guides/docs_contributing.rst @@ -309,7 +309,7 @@ After that, you can use the following structure to include the image in the docs .. code-block:: - .. figure:: ../_static/arduino_i2c_master.png + .. figure:: ../../_static/arduino_i2c_master.png :align: center :width: 720 :figclass: align-center diff --git a/docs/source/guides/guides.rst b/docs/en/guides/guides.rst similarity index 100% rename from docs/source/guides/guides.rst rename to docs/en/guides/guides.rst diff --git a/docs/source/guides/tools_menu.rst b/docs/en/guides/tools_menu.rst similarity index 99% rename from docs/source/guides/tools_menu.rst rename to docs/en/guides/tools_menu.rst index 96b3bcc3674..41c8878bf6e 100644 --- a/docs/source/guides/tools_menu.rst +++ b/docs/en/guides/tools_menu.rst @@ -240,7 +240,7 @@ The USB Mass Storage Class, or USB MSC, is a class used for storage devices, lik This option can be used to ``Enable`` or ``Disable`` this function at the boot. If this option is ``Enabled``, once the device is connected via USB, one new storage device will appear in the system as a storage drive. Use this new storage drive to write and read files or to drop a new firmware binary to flash the device. -.. figure:: ../_static/usb_msc_drive.png +.. figure:: ../../_static/usb_msc_drive.png :align: center :width: 720 :figclass: align-center diff --git a/docs/source/index.rst b/docs/en/index.rst similarity index 100% rename from docs/source/index.rst rename to docs/en/index.rst diff --git a/docs/source/installing.rst b/docs/en/installing.rst similarity index 94% rename from docs/source/installing.rst rename to docs/en/installing.rst index c3bd268949b..5f29ce10028 100644 --- a/docs/source/installing.rst +++ b/docs/en/installing.rst @@ -13,7 +13,7 @@ To install Arduino-ESP32 support, you can use one of the following options. Installing using Arduino IDE ---------------------------- -.. figure:: _static/logo_arduino.png +.. figure:: ../_static/logo_arduino.png :align: center :width: 200 :figclass: align-center @@ -42,21 +42,21 @@ To start the installation process using the Boards Managaer, follow these steps: - Start Arduino and open the Preferences window. -.. figure:: _static/install_guide_preferences.png +.. figure:: ../_static/install_guide_preferences.png :align: center :width: 600 :figclass: align-center - Enter one of the release links above into *Additional Board Manager URLs* field. You can add multiple URLs, separating them with commas. -.. figure:: _static/install_guide_boards_manager_url.png +.. figure:: ../_static/install_guide_boards_manager_url.png :align: center :width: 600 :figclass: align-center - Open Boards Manager from Tools > Board menu and install *esp32* platform (and do not forget to select your ESP32 board from Tools > Board menu after installation). -.. figure:: _static/install_guide_boards_manager_esp32.png +.. figure:: ../_static/install_guide_boards_manager_esp32.png :align: center :width: 600 :figclass: align-center @@ -66,7 +66,7 @@ To start the installation process using the Boards Managaer, follow these steps: Installing using PlatformIO --------------------------- -.. figure:: _static/logo_pio.png +.. figure:: ../_static/logo_pio.png :align: center :width: 200 :figclass: align-center @@ -164,7 +164,7 @@ Steps to install Arduino ESP32 support on Windows: - Select ``Clone Existing Repository`` -.. figure:: _static/win-gui-1.png +.. figure:: ../_static/win-gui-1.png :align: center :width: 600 :figclass: align-center @@ -177,13 +177,13 @@ Steps to install Arduino ESP32 support on Windows: **Step 2** -.. figure:: _static/win-gui-2.png +.. figure:: ../_static/win-gui-2.png :align: center :figclass: align-center **Step 3** -.. figure:: _static/win-gui-3.png +.. figure:: ../_static/win-gui-3.png :align: center :figclass: align-center @@ -192,7 +192,7 @@ Steps to install Arduino ESP32 support on Windows: **Step 4** -.. figure:: _static/win-gui-4.png +.. figure:: ../_static/win-gui-4.png :align: center :figclass: align-center @@ -200,7 +200,7 @@ Steps to install Arduino ESP32 support on Windows: **Step 5** -.. figure:: _static/win-gui-5.png +.. figure:: ../_static/win-gui-5.png :align: center :figclass: align-center @@ -210,7 +210,7 @@ Steps to install Arduino ESP32 support on Windows: 4. Select the COM port that the board is attached to 5. Compile and upload (You might need to hold the boot button while uploading) -.. figure:: _static/arduino-ide.png +.. figure:: ../_static/arduino-ide.png :align: center :figclass: align-center @@ -219,27 +219,27 @@ How to update to the latest code 1. Start ``Git GUI`` and you should see the repository under ``Open Recent Repository``. Click on it! -.. figure:: _static/win-gui-update-1.png +.. figure:: ../_static/win-gui-update-1.png :align: center :figclass: align-center 1. From menu ``Remote`` select ``Fetch from`` > ``origin`` -.. figure:: _static/win-gui-update-2.png +.. figure:: ../_static/win-gui-update-2.png :align: center :figclass: align-center 1. Wait for git to pull any changes and close ``Git GUI`` 2. Open ``[ARDUINO_SKETCHBOOK_DIR]/hardware/espressif/esp32/tools`` and double-click ``get.exe`` -.. figure:: _static/win-gui-4.png +.. figure:: ../_static/win-gui-4.png :align: center :figclass: align-center Linux ----- -.. figure:: _static/logo_linux.png +.. figure:: ../_static/logo_linux.png :align: center :width: 200 :figclass: align-center diff --git a/docs/source/lib_builder.rst b/docs/en/lib_builder.rst similarity index 100% rename from docs/source/lib_builder.rst rename to docs/en/lib_builder.rst diff --git a/docs/source/libraries.rst b/docs/en/libraries.rst similarity index 100% rename from docs/source/libraries.rst rename to docs/en/libraries.rst diff --git a/docs/source/make.rst b/docs/en/make.rst similarity index 100% rename from docs/source/make.rst rename to docs/en/make.rst diff --git a/docs/source/ota_web_update.rst b/docs/en/ota_web_update.rst similarity index 93% rename from docs/source/ota_web_update.rst rename to docs/en/ota_web_update.rst index b637f0206b3..17cbe3583f5 100644 --- a/docs/source/ota_web_update.rst +++ b/docs/en/ota_web_update.rst @@ -36,14 +36,14 @@ Prepare the sketch and configuration for initial upload with a serial port - Update ssid and pass in the sketch so the module can join your Wi-Fi network - Open File > Preferences, look for “Show verbose output during:” and check out “compilation” option -.. figure:: _static/ota_esp32_verbose.png +.. figure:: ../_static/ota_esp32_verbose.png :align: center :figclass: align-center - Upload sketch (Ctrl+U) - Now open web browser and enter the url, i.e. http://esp32.local. Once entered, browser should display a form -.. figure:: _static/ota_esp32_login.png +.. figure:: ../_static/ota_esp32_login.png :align: center :figclass: align-center @@ -56,7 +56,7 @@ Prepare the sketch and configuration for initial upload with a serial port Now click on the Login button and browser will display an upload form -.. figure:: _static/ota_esp32_upload.png +.. figure:: ../_static/ota_esp32_upload.png :align: center :figclass: align-center @@ -67,7 +67,7 @@ Exporting Binary file of the Firmware (Code) - Open up the Code, for Exporting up Binary file - Now go to Sketch > export compiled Binary -.. figure:: _static/ota_export_to_binary.png +.. figure:: ../_static/ota_export_to_binary.png :align: center :figclass: align-center diff --git a/docs/source/troubleshooting.rst b/docs/en/troubleshooting.rst similarity index 100% rename from docs/source/troubleshooting.rst rename to docs/en/troubleshooting.rst diff --git a/docs/source/tutorials/basic.rst b/docs/en/tutorials/basic.rst similarity index 97% rename from docs/source/tutorials/basic.rst rename to docs/en/tutorials/basic.rst index 34d9a05c094..8b932987bea 100644 --- a/docs/source/tutorials/basic.rst +++ b/docs/en/tutorials/basic.rst @@ -21,7 +21,7 @@ Here are the steps for this tutorial. 1. Open the Arduino IDE -.. figure:: ../_static/tutorials/basic/tutorial_basic_ide.png +.. figure:: ../../_static/tutorials/basic/tutorial_basic_ide.png :align: center :width: 600 :alt: Arduino IDE (click to enlarge) diff --git a/docs/source/tutorials/blink.rst b/docs/en/tutorials/blink.rst similarity index 100% rename from docs/source/tutorials/blink.rst rename to docs/en/tutorials/blink.rst diff --git a/docs/source/tutorials/cdc_dfu_flash.rst b/docs/en/tutorials/cdc_dfu_flash.rst similarity index 100% rename from docs/source/tutorials/cdc_dfu_flash.rst rename to docs/en/tutorials/cdc_dfu_flash.rst diff --git a/docs/source/tutorials/io_mux.rst b/docs/en/tutorials/io_mux.rst similarity index 98% rename from docs/source/tutorials/io_mux.rst rename to docs/en/tutorials/io_mux.rst index 12e0a9c9c0c..03b10449013 100644 --- a/docs/source/tutorials/io_mux.rst +++ b/docs/en/tutorials/io_mux.rst @@ -23,7 +23,7 @@ GPIO Matrix and Pin Mux The ESP32 architecture includes the capability of configuring some peripherals to any of the GPIOs pins, managed by the `IO MUX GPIO`_. Essentially, this capability means that we can route the internal peripheral into a different physical pin using the IO MUX and the GPIO Matrix. -.. figure:: ../_static/tutorials/peripherals/tutorial_peripheral_diagram.png +.. figure:: ../../_static/tutorials/peripherals/tutorial_peripheral_diagram.png :align: center :width: 600 :figclass: align-center diff --git a/docs/source/tutorials/partition_table.rst b/docs/en/tutorials/partition_table.rst similarity index 100% rename from docs/source/tutorials/partition_table.rst rename to docs/en/tutorials/partition_table.rst diff --git a/docs/source/tutorials/preferences.rst b/docs/en/tutorials/preferences.rst similarity index 100% rename from docs/source/tutorials/preferences.rst rename to docs/en/tutorials/preferences.rst diff --git a/docs/source/tutorials/tutorials.rst b/docs/en/tutorials/tutorials.rst similarity index 100% rename from docs/source/tutorials/tutorials.rst rename to docs/en/tutorials/tutorials.rst diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 6247f7e2317..00000000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/requirements.txt b/docs/requirements.txt index 9e40946ec2b..97b552574b9 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,6 +1,3 @@ -# This is a list of python packages used to generate documentation. This file is used with pip: -# pip install --user -r requirements.txt -# -# matplotlib is currently required only by the script generate_chart.py -sphinx-copybutton==0.3.0 +esp-docs==1.4.* +sphinx-copybutton==0.5.0 sphinx-tabs==3.2.0 \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index 402c1e293d5..00000000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,68 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -import os -import sys -# sys.path.insert(0, os.path.abspath('.')) - - -# -- Project information ----------------------------------------------------- - -project = 'Arduino-ESP32' -copyright = '2022, Espressif' -author = 'Espressif' - -# The full version, including alpha/beta/rc tags -release = '2.0.6' - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - 'sphinx_copybutton', - 'sphinx_tabs.tabs' -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' - -# The master toctree document. -master_doc = 'index' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = [] - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = 'default' -html_logo = '_static/logo_espressif.png' - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# Style -# pygments_style = "sphinx" From bdd9d1c0b864f7e7cbf4829eb595ebeedf4a1bea Mon Sep 17 00:00:00 2001 From: pedrominatel Date: Tue, 19 Sep 2023 08:40:05 +0100 Subject: [PATCH 02/21] Documentation CI build changed to ESP-Docs --- .github/workflows/docs.yml | 4 ++-- .readthedocs.yaml | 2 +- docs/conf_common.py | 2 ++ 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index f01fb76ee84..de383bce1bb 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -34,5 +34,5 @@ jobs: sudo apt install python3-pip python3-setuptools # GitHub CI installs pip3 and setuptools outside the path. # Update the path to include them and run. - PATH=/home/runner/.local/bin:$PATH pip3 install --user -r ./docs/requirements.txt - cd ./docs && PATH=/home/runner/.local/bin:$PATH SPHINXOPTS="-W" make html + PATH=/home/runner/.local/bin:$PATH pip install -r requirements.txt --prefer-binary + cd ./docs && PATH=/home/runner/.local/bin:$PATH SPHINXOPTS="-W" build-docs -l en -t esp32 diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 259c19f98fd..498a30c3f4f 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -13,7 +13,7 @@ build: # Build documentation in the docs/ directory with Sphinx sphinx: - configuration: docs/source/conf.py + configuration: docs/en/conf.py python: install: diff --git a/docs/conf_common.py b/docs/conf_common.py index 9aab8d4a224..705659a3b66 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -4,6 +4,8 @@ languages = ["en"] + + # link roles config github_repo = "espressif/arduino-esp32" From 58d7bf9951a8007fe205f9b0f5cb14c5526df704 Mon Sep 17 00:00:00 2001 From: pedrominatel Date: Tue, 19 Sep 2023 08:44:13 +0100 Subject: [PATCH 03/21] Fix documentation CI build --- .github/workflows/docs.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index de383bce1bb..f99568aa764 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -34,5 +34,6 @@ jobs: sudo apt install python3-pip python3-setuptools # GitHub CI installs pip3 and setuptools outside the path. # Update the path to include them and run. - PATH=/home/runner/.local/bin:$PATH pip install -r requirements.txt --prefer-binary - cd ./docs && PATH=/home/runner/.local/bin:$PATH SPHINXOPTS="-W" build-docs -l en -t esp32 + cd ./docs + PATH=/home/runner/.local/bin:$PATH pip3 install -r requirements.txt --prefer-binary + PATH=/home/runner/.local/bin:$PATH SPHINXOPTS="-W" build-docs -l en -t esp32 From 11e53c535bb31e13167706edee12bc555cc951d0 Mon Sep 17 00:00:00 2001 From: pedrominatel Date: Tue, 19 Sep 2023 09:01:24 +0100 Subject: [PATCH 04/21] Docs build target fix --- .github/workflows/docs.yml | 4 ++-- docs/conf_common.py | 9 ++++++++- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index f99568aa764..705005e6b6d 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,4 +1,4 @@ -name: ReadTheDocs CI +name: Documentation Build CI on: push: @@ -16,7 +16,7 @@ on: jobs: build-docs: - name: Build ReadTheDocs + name: Build ESP-Docs runs-on: ubuntu-22.04 defaults: run: diff --git a/docs/conf_common.py b/docs/conf_common.py index 705659a3b66..8522c680667 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -4,7 +4,14 @@ languages = ["en"] - +idf_targets = [ + "esp32", + "esp32s2", + "esp32s3", + "esp32c3", + "esp32c6", + "esp32h2", +] # link roles config github_repo = "espressif/arduino-esp32" From e515a6a1d11780fbd8780ad658ae91fb8baf99d0 Mon Sep 17 00:00:00 2001 From: pedrominatel Date: Tue, 19 Sep 2023 15:22:44 +0100 Subject: [PATCH 05/21] Added CI for deploy docs --- .github/workflows/docs.yml | 2 +- .github/workflows/docs_deploy.yml | 46 +++++++++++++++++++ ...uino-esp32_versions.js => docs_version.js} | 2 +- docs/conf_common.py | 21 ++++++++- docs/en/conf.py | 5 +- docs/en/index.rst | 2 +- docs/utils.sh | 18 ++++++++ 7 files changed, 91 insertions(+), 5 deletions(-) create mode 100644 .github/workflows/docs_deploy.yml rename docs/_static/{arduino-esp32_versions.js => docs_version.js} (92%) create mode 100644 docs/utils.sh diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 705005e6b6d..98699a680cd 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -36,4 +36,4 @@ jobs: # Update the path to include them and run. cd ./docs PATH=/home/runner/.local/bin:$PATH pip3 install -r requirements.txt --prefer-binary - PATH=/home/runner/.local/bin:$PATH SPHINXOPTS="-W" build-docs -l en -t esp32 + PATH=/home/runner/.local/bin:$PATH SPHINXOPTS="-W" build-docs -l en -t esp32 esp32s2 esp32s3 esp32c6 esp32h2 diff --git a/.github/workflows/docs_deploy.yml b/.github/workflows/docs_deploy.yml new file mode 100644 index 00000000000..282ab264a16 --- /dev/null +++ b/.github/workflows/docs_deploy.yml @@ -0,0 +1,46 @@ +name: Documentation Deploy CI + +on: + workflow_dispatch: + release: + types: + - created + paths: + - 'docs/**' + - '.github/workflows/docs_deploy.yml' + +jobs: + + deploy-preview-docs: + name: Deploy Documentation + runs-on: ubuntu-22.04 + defaults: + run: + shell: bash + steps: + - uses: actions/checkout@v2 + with: + submodules: true + - uses: actions/setup-python@v2 + with: + python-version: '3.10' + - name: Deploy Preview + env: + DOCS_BUILD_DIR: "./docs/_build/" + DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_DEPLOY_KEY }} + DOCS_DEPLOY_SERVER: ${{ secrets.DOCS_PREV_SERVER }} + DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_PREV_SERVER_USER }} + DOCS_DEPLOY_PATH: ${{ secrets.DOCS_PREV_PATH }} + DOCS_DEPLOY_URL_BASE: ${{ secrets.DOCS_PREV_URL }} + run: | + sudo apt update + sudo apt install python3-pip python3-setuptools + source ./docs/utils.sh + add_doc_server_ssh_keys $DOCS_DEPLOY_PRIVATEKEY $DOCS_DEPLOY_SERVER $DOCS_DEPLOY_SERVER_USER + export GIT_VER=$(git describe --always) + echo "PIP install requirements..." + pip3 install --user -r ./docs/requirements.txt + echo "Building the Docs..." + cd ./docs && build-docs -l en + echo "Deploy the Docs..." + deploy-docs diff --git a/docs/_static/arduino-esp32_versions.js b/docs/_static/docs_version.js similarity index 92% rename from docs/_static/arduino-esp32_versions.js rename to docs/_static/docs_version.js index b4b772d5c45..a511b79dc31 100644 --- a/docs/_static/arduino-esp32_versions.js +++ b/docs/_static/docs_version.js @@ -11,6 +11,6 @@ var DOCUMENTATION_VERSIONS = { { text: "ESP32-S3", value: "esp32s3"}, { text: "ESP32-C3", value: "esp32c3"}, { text: "ESP32-H2", value: "esp32h2"}, - { text: "ESP32C6", value: "esp32c6"}, + { text: "ESP32-C6", value: "esp32c6"}, ] }; \ No newline at end of file diff --git a/docs/conf_common.py b/docs/conf_common.py index 8522c680667..3320558c3db 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -33,7 +33,26 @@ "index.rst", ] +ESP32S2_DOCS = ESP32_DOCS + +ESP32C3_DOCS = ESP32S2_DOCS + +ESP32S3_DOCS = ESP32S2_DOCS + +ESP32C6_DOCS = ESP32S2_DOCS + +ESP32H2_DOCS = ESP32S2_DOCS + +conditional_include_dict = { + "esp32": ESP32_DOCS, + "esp32s2": ESP32S2_DOCS, + "esp32c3": ESP32C3_DOCS, + "esp32s3": ESP32S3_DOCS, + "esp32c6": ESP32C6_DOCS, + "esp32h2": ESP32H2_DOCS, +} + # Extra options required by sphinx_idf_theme project_slug = "arduino-esp32" -versions_url = "./_static/arduino-esp32_versions.js" +versions_url = "./_static/docs_version.js" diff --git a/docs/en/conf.py b/docs/en/conf.py index ea8f20e4604..4d1208f256a 100644 --- a/docs/en/conf.py +++ b/docs/en/conf.py @@ -15,9 +15,12 @@ sys.path.insert(0, os.path.abspath('../')) from conf_common import * # noqa: F403,F401 +import datetime +current_year = datetime.datetime.now().year + # General information about the project. project = u'Arduino ESP32' -copyright = u'2016 - 2023, Espressif Systems (Shanghai) Co., Ltd' +copyright = u'2016 - {}, Espressif Systems (Shanghai) Co., Ltd'.format(current_year) pdf_title = u'Arduino ESP32 Documentation Guide' # The language for content autogenerated by Sphinx. Refer to documentation diff --git a/docs/en/index.rst b/docs/en/index.rst index f504dc342e0..345e75bd5ee 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -1,5 +1,5 @@ ############################################# -Welcome to ESP32 Arduino Core's documentation +Welcome to {IDF_TARGET_NAME} Arduino Core's documentation ############################################# Here you will find all the relevant information about the project. diff --git a/docs/utils.sh b/docs/utils.sh new file mode 100644 index 00000000000..91e283d462f --- /dev/null +++ b/docs/utils.sh @@ -0,0 +1,18 @@ +# Bash helper functions for adding SSH keys + +function add_ssh_keys() { + local key_string="${1}" + mkdir -p ~/.ssh + chmod 700 ~/.ssh + echo -n "${key_string}" >~/.ssh/id_rsa_base64 + base64 -w 0 ~/.ssh/id_rsa_base64 | base64 -di >~/.ssh/id_rsa + chmod 600 ~/.ssh/id_rsa +} + +function add_doc_server_ssh_keys() { + local key_string="${1}" + local server_url="${2}" + local server_user="${3}" + add_ssh_keys "${key_string}" + echo -e "Host ${server_url}\n\tStrictHostKeyChecking no\n\tUser ${server_user}\n" >>~/.ssh/config +} \ No newline at end of file From 7326a41c1f524bb35a3e0cd12de2080af6c143ff Mon Sep 17 00:00:00 2001 From: pedrominatel Date: Tue, 19 Sep 2023 15:32:33 +0100 Subject: [PATCH 06/21] Fix index.rst title wirh ESP target --- docs/en/index.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/en/index.rst b/docs/en/index.rst index 345e75bd5ee..3ed77588b26 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -1,8 +1,8 @@ -############################################# -Welcome to {IDF_TARGET_NAME} Arduino Core's documentation -############################################# +####################################### +Welcome to Arduino Core's documentation +####################################### -Here you will find all the relevant information about the project. +Here you will find all the relevant information about the project based on the {IDF_TARGET_NAME}. .. note:: This is a work in progress documentation and we will appreciate your help! We are looking for contributors! From e2f52dbcf7478f7ab7056dad8fc438022d24e6c7 Mon Sep 17 00:00:00 2001 From: pedrominatel Date: Mon, 25 Sep 2023 15:03:59 +0100 Subject: [PATCH 07/21] Added versions to JS file and docs as artifact --- .github/workflows/docs.yml | 5 +++++ docs/_static/arduino_versions.js | 28 ++++++++++++++++++++++++++++ docs/_static/docs_version.js | 16 ---------------- docs/conf_common.py | 6 +----- 4 files changed, 34 insertions(+), 21 deletions(-) create mode 100644 docs/_static/arduino_versions.js delete mode 100644 docs/_static/docs_version.js diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 98699a680cd..e0dc48653ef 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -37,3 +37,8 @@ jobs: cd ./docs PATH=/home/runner/.local/bin:$PATH pip3 install -r requirements.txt --prefer-binary PATH=/home/runner/.local/bin:$PATH SPHINXOPTS="-W" build-docs -l en -t esp32 esp32s2 esp32s3 esp32c6 esp32h2 + - name: Archive Docs + uses: actions/upload-artifact@v2 + with: + name: docs + path: docs \ No newline at end of file diff --git a/docs/_static/arduino_versions.js b/docs/_static/arduino_versions.js new file mode 100644 index 00000000000..5d6e2d1451d --- /dev/null +++ b/docs/_static/arduino_versions.js @@ -0,0 +1,28 @@ +var DOCUMENTATION_VERSIONS = { + DEFAULTS: { has_targets: false, + supported_targets: [ "esp32" ] + }, + VERSIONS: [ + { name: "latest", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3", "esp32h2", "esp32c6" ] }, + // 2.0.13 + { name: "release-2.0.13", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3" ] }, + // 2.0.12 + { name: "release-2.0.12", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3" ] }, + // 2.0.11 + { name: "release-2.0.11", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3" ] }, + // 2.0.10 + { name: "release-2.0.10", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3" ] }, + // 2.0.9 + { name: "release-2.0.9", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3" ] }, + // 2.0.8 + { name: "release-2.0.8", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3" ] }, + ], + IDF_TARGETS: [ + { text: "ESP32", value: "esp32"}, + { text: "ESP32-S2", value: "esp32s2"}, + { text: "ESP32-S3", value: "esp32s3"}, + { text: "ESP32-C3", value: "esp32c3"}, + { text: "ESP32-H2", value: "esp32h2"}, + { text: "ESP32-C6", value: "esp32c6"}, + ] +}; diff --git a/docs/_static/docs_version.js b/docs/_static/docs_version.js deleted file mode 100644 index a511b79dc31..00000000000 --- a/docs/_static/docs_version.js +++ /dev/null @@ -1,16 +0,0 @@ -var DOCUMENTATION_VERSIONS = { - DEFAULTS: { has_targets: false, - supported_targets: [ "esp32" ] - }, - VERSIONS: [ - { name: "latest", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3", "esp32h2", "esp32c6" ] }, - ], - IDF_TARGETS: [ - { text: "ESP32", value: "esp32"}, - { text: "ESP32-S2", value: "esp32s2"}, - { text: "ESP32-S3", value: "esp32s3"}, - { text: "ESP32-C3", value: "esp32c3"}, - { text: "ESP32-H2", value: "esp32h2"}, - { text: "ESP32-C6", value: "esp32c6"}, - ] -}; \ No newline at end of file diff --git a/docs/conf_common.py b/docs/conf_common.py index 3320558c3db..ded9c5673cb 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -34,13 +34,9 @@ ] ESP32S2_DOCS = ESP32_DOCS - ESP32C3_DOCS = ESP32S2_DOCS - ESP32S3_DOCS = ESP32S2_DOCS - ESP32C6_DOCS = ESP32S2_DOCS - ESP32H2_DOCS = ESP32S2_DOCS conditional_include_dict = { @@ -55,4 +51,4 @@ # Extra options required by sphinx_idf_theme project_slug = "arduino-esp32" -versions_url = "./_static/docs_version.js" +versions_url = "./_static/arduino_versions.js" From f7151e0e6689d055914104cd2620c9dfea940cbf Mon Sep 17 00:00:00 2001 From: pedrominatel Date: Mon, 4 Dec 2023 11:42:11 +0800 Subject: [PATCH 08/21] Resolving ADC conflict issue --- docs/en/api/adc.rst | 167 +++++++++++++++++++++++++++++++------------- 1 file changed, 120 insertions(+), 47 deletions(-) diff --git a/docs/en/api/adc.rst b/docs/en/api/adc.rst index 7e8265afb8f..8ab252e181b 100644 --- a/docs/en/api/adc.rst +++ b/docs/en/api/adc.rst @@ -11,13 +11,17 @@ to a digital form so that it can be read and processed by a microcontroller. ADCs are very useful in control and monitoring applications since most sensors (e.g., temperature, pressure, force) produce analogue output voltages. -.. note:: Each SoC or module has a different number of ADC's with a different number of channels and pins availible. Refer to datasheet of each board for more info. +.. note:: Each SoC or module has a different number of ADC's with a different number of channels and pins available. Refer to datasheet of each board for more info. Arduino-ESP32 ADC API --------------------- -ADC common API -************** +ADC OneShot mode +**************** + + +The ADC OneShot mode API is fully compatible with Arduino's ``analogRead`` function. +When you call the ``analogRead`` or ``analogReadMillivolts`` function, it returns the result of a single conversion on the requested pin. analogRead ^^^^^^^^^^ @@ -30,12 +34,12 @@ This function is used to get the ADC raw value for a given pin/ADC channel. * ``pin`` GPIO pin to read analog value -This function will return analog raw value. +This function will return analog raw value (non-calibrated). analogReadMillivolts ^^^^^^^^^^^^^^^^^^^^ -This function is used to get ADC value for a given pin/ADC channel in millivolts. +This function is used to get ADC raw value for a given pin/ADC channel and convert it to calibrated result in millivolts. .. code-block:: arduino @@ -43,7 +47,7 @@ This function is used to get ADC value for a given pin/ADC channel in millivolts * ``pin`` GPIO pin to read analog value -This function will return analog value in millivolts. +This function will return analog value in millivolts (calibrated). analogReadResolution ^^^^^^^^^^^^^^^^^^^^ @@ -62,19 +66,6 @@ Range is 1 - 16 .The default value will be used, if this function is not used. * ``bits`` sets analog read resolution -analogSetClockDiv -^^^^^^^^^^^^^^^^^ - -This function is used to set the divider for the ADC clock. - -Range is 1 - 255. Default value is 1. - -.. code-block:: arduino - - void analogSetClockDiv(uint8_t clockDiv); - -* ``clockDiv`` sets the divider for ADC clock. - analogSetAttenuation ^^^^^^^^^^^^^^^^^^^^ @@ -95,7 +86,7 @@ The measurable input voltage differs for each chip, see table below for detailed ``ADC_ATTEN_DB_0`` 100 mV ~ 950 mV ``ADC_ATTEN_DB_2_5`` 100 mV ~ 1250 mV ``ADC_ATTEN_DB_6`` 150 mV ~ 1750 mV - ``ADC_ATTEN_DB_11`` 150 mV ~ 2450 mV + ``ADC_ATTEN_DB_11`` 150 mV ~ 3100 mV ===================== =========================================== .. tab:: ESP32-S2 @@ -148,24 +139,12 @@ This function is used to set the attenuation for a specific pin/ADC channel. For * ``pin`` selects specific pin for attenuation settings. * ``attenuation`` sets the attenuation. - -adcAttachPin -^^^^^^^^^^^^ - -This function is used to attach the pin to ADC (it will also clear any other analog mode that could be on) - -.. code-block:: arduino - - bool adcAttachPin(uint8_t pin); - -This function will return ``true`` if configuration is successful. Else returns ``false``. - -ADC API specific for ESP32 chip -******************************* analogSetWidth ^^^^^^^^^^^^^^ +.. note:: This function is only available for ESP32 chip. + This function is used to set the hardware sample bits and read resolution. Default is 12bit (0 - 4095). Range is 9 - 12. @@ -173,36 +152,130 @@ Range is 9 - 12. .. code-block:: arduino void analogSetWidth(uint8_t bits); - -analogSetVRefPin + +ADC Continuous mode +******************* + +ADC Continuous mode is an API designed for performing analog conversions on multiple pins in the background, +with the feature of receiving a callback upon completion of these conversions to access the results. + +This API allows you to specify the desired number of conversions per pin within a single cycle, along with its corresponding sampling rate. +The outcome of the ``analogContinuousRead`` function is an array of ``adc_continuous_data_t`` structures. +These structures hold both the raw average value and the average value in millivolts for each pin. + +analogContinuous ^^^^^^^^^^^^^^^^ -This function is used to set pin to use for ADC calibration if the esp is not already calibrated (pins 25, 26 or 27). +This function is used to configure ADC continuous peripheral on selected pins. .. code-block:: arduino - void analogSetVRefPin(uint8_t pin); + bool analogContinuous(uint8_t pins[], size_t pins_count, uint32_t conversions_per_pin, uint32_t sampling_freq_hz, void (*userFunc)(void)); -* ``pin`` GPIO pin to set VRefPin for ADC calibration +* ``pins[]`` array of pins to be set up +* ``pins_count`` count of pins in array +* ``conversions_per_pin`` sets how many conversions per pin will run each ADC cycle +* ``sampling_freq_hz`` sets sampling frequency of ADC in Hz +* ``userFunc`` sets callback function to be called after adc conversion is done (can be set to ``NULL``) -hallRead -^^^^^^^^ +This function will return ``true`` if configuration is successful. +If ``false`` is returned, error occurs and ADC continuous was not configured. -This function is used to get the ADC value of the HALL sensor conneted to pins 36(SVP) and 39(SVN). +analogContinuousRead +^^^^^^^^^^^^^^^^^^^^ + +This function is used to read ADC continuous data to the result buffer. The result buffer is an array of ``adc_continuos_data_t``. .. code-block:: arduino - int hallRead(); - -This function will return the hall sensor value. + typedef struct { + uint8_t pin; /*! AnalogReadSerial. .. literalinclude:: ../../../libraries/ESP32/examples/AnalogRead/AnalogRead.ino :language: arduino -Or you can run Arduino example 01.Basics -> AnalogReadSerial. +Here is an example of how to use the ADC in Continuous mode. + +.. literalinclude:: ../../../libraries/ESP32/examples/AnalogReadContinuous/AnalogReadContinuous.ino + :language: arduino From f9a5f4b9bfec83e7bf63b84eece22ac83340ea18 Mon Sep 17 00:00:00 2001 From: pedrominatel Date: Thu, 7 Dec 2023 10:21:12 +0800 Subject: [PATCH 09/21] Merge conflicts resolved in the new docs --- docs/en/api/wifi.rst | 107 ++- docs/en/boards/boards.rst | 6 + docs/en/conf.py | 5 +- docs/en/getting_started.rst | 2 + docs/en/index.rst | 1 + docs/en/installing.rst | 2 + .../migration_guides/2.x_to_3.0.rst | 0 .../migration_guides/migration_guides.rst | 0 docs/en/ota_web_update.rst | 3 + docs/source/api/adc.rst | 281 -------- docs/source/api/wifi.rst | 675 ------------------ docs/source/boards/boards.rst | 120 ---- docs/source/conf.py | 72 -- docs/source/getting_started.rst | 155 ---- docs/source/index.rst | 23 - docs/source/installing.rst | 363 ---------- docs/source/ota_web_update.rst | 79 -- 17 files changed, 123 insertions(+), 1771 deletions(-) rename docs/{source => en}/migration_guides/2.x_to_3.0.rst (100%) rename docs/{source => en}/migration_guides/migration_guides.rst (100%) delete mode 100644 docs/source/api/adc.rst delete mode 100644 docs/source/api/wifi.rst delete mode 100644 docs/source/boards/boards.rst delete mode 100644 docs/source/conf.py delete mode 100644 docs/source/getting_started.rst delete mode 100644 docs/source/index.rst delete mode 100644 docs/source/installing.rst delete mode 100644 docs/source/ota_web_update.rst diff --git a/docs/en/api/wifi.rst b/docs/en/api/wifi.rst index d5632ae7717..9a4c1b17aba 100644 --- a/docs/en/api/wifi.rst +++ b/docs/en/api/wifi.rst @@ -50,6 +50,102 @@ Common API Here are the common APIs that are used for both modes, AP and STA. +onEvent (and removeEvent) +************************* + +Registers a caller-supplied function to be called when WiFi events +occur. Several forms are available. + +Function pointer callback taking the event ID: + +.. code-block:: arduino + + typedef void (*WiFiEventCb)(arduino_event_id_t); + wifi_event_id_t onEvent(WiFiEventCb, arduino_event_id_t = ARDUINO_EVENT_MAX); + +Function pointer callback taking an event-ID-and-info struct: + +.. code-block:: arduino + + typedef struct{ + arduino_event_id_t event_id; + arduino_event_info_t event_info; + } arduino_event_t; + + typedef void (*WiFiEventSysCb)(arduino_event_t *); + wifi_event_id_t onEvent(WiFiEventSysCb, arduino_event_id_t = ARDUINO_EVENT_MAX); + +Callback using ``std::function`` taking event ID and info separately: + +.. code-block:: arduino + + typedef std::function WiFiEventFuncCb; + wifi_event_id_t onEvent(WiFiEventFuncCb, arduino_event_id_t = ARDUINO_EVENT_MAX); + +A similar set of functions are available to remove callbacks: + +.. code-block:: arduino + + void removeEvent(WiFiEventCb, arduino_event_id_t = ARDUINO_EVENT_MAX); + void removeEvent(WiFiEventSysCb, arduino_event_id_t = ARDUINO_EVENT_MAX); + void removeEvent(wifi_event_id_t = ARDUINO_EVENT_MAX); + +In all cases, the subscribing function accepts an optional event type to +invoke the callback only for that specific event; with the default +``ARDUINO_EVENT_MAX``, the callback will be invoked for all WiFi events. + +Any callback function is given the event type in a parameter. +Some of the possible callback function formats also take an +``arduino_event_info_t`` (or use ``arduino_event_t`` which includes both +ID and info) which is a union of structs with additional information +about different event types. + +See +`WiFiGeneric.h `_ +for the list of event types and "info" substructures, and also see a full +example of event handling: `events example`_. + +.. warning:: + + Event callback functions are invoked on a separate + `thread `_ + (`FreeRTOS task `_) + independent of the main application thread that runs ``setup()`` and + ``loop()``. Callback functions must therefore be + `thread-safe `_; + they must not access shared/global variables directly without locking, + and must only call similarly thread-safe functions. + + Some core operations like ``Serial.print()`` are thread-safe but many + functions are not. Notably, ``WiFi.onEvent()`` and ``WiFi.removeEvent()`` + are not thread-safe and should never be invoked from a callback thread. + +setHostname (and getHostname) +***************************** + +Sets the name the DHCP client uses to identify itself. In a typical network +setup this will be the name that shows up in the Wi-Fi router's device list. +The hostname must be no longer than 32 characters. + +.. code-block:: arduino + + setHostname(const char *hostname); + +If the hostname is never specified, a default one will be assigned based +on the chip type and MAC address. The current hostname (default or custom) +may be retrieved: + +.. code-block:: arduino + + const char *getHostname(); + +.. warning:: + + The ``setHostname()`` function must be called BEFORE WiFi is started with + ``WiFi.begin()``, ``WiFi.softAP()``, ``WiFi.mode()``, or ``WiFi.run()``. + To change the name, reset WiFi with ``WiFi.mode(WIFI_MODE_NULL)``, + then proceed with ``WiFi.setHostname(...)`` and restart WiFi from scratch. + useStaticBuffers **************** @@ -552,6 +648,8 @@ To see how to use the ``WiFiScan``, take a look at the ``WiFiScan.ino`` example Examples -------- +`Complete list of WiFi examples `_. + .. _ap example: Wi-Fi AP Example @@ -568,5 +666,10 @@ Wi-Fi STA Example .. literalinclude:: ../../../libraries/WiFi/examples/WiFiClient/WiFiClient.ino :language: arduino -References ----------- +.. _events example: + +Wi-Fi Events Example +******************** + +.. literalinclude:: ../../../libraries/WiFi/examples/WiFiClientEvents/WiFiClientEvents.ino + :language: arduino diff --git a/docs/en/boards/boards.rst b/docs/en/boards/boards.rst index 9a1d2217dac..7323ba2a933 100644 --- a/docs/en/boards/boards.rst +++ b/docs/en/boards/boards.rst @@ -22,6 +22,9 @@ The ESP32 is divided by family: * Wi-Fi only * ESP32-C * Wi-Fi and BLE 5 + * IEEE 802.15.4 (only in ESP32-C6) +* ESP32-H + * BLE and IEEE 802.15.4 For each family, we have SoC variants with some differentiation. The differences are more about the embedded flash and its size and the number of the cores (dual or single). @@ -71,6 +74,9 @@ Espressif ESP32-S2-Saola-1 ESP32-C3-DevKitM-1 +.. note:: + Only a few development boards are described on this documentation page. For more information about other Espressif development boards please refer to the `Espressif website `_. + Third Party ----------- diff --git a/docs/en/conf.py b/docs/en/conf.py index 4d1208f256a..9979662dae0 100644 --- a/docs/en/conf.py +++ b/docs/en/conf.py @@ -25,4 +25,7 @@ # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -language = 'en' \ No newline at end of file +language = 'en' + +# Tracking ID for Google Analytics +google_analytics_id = 'G-F58JM78930' \ No newline at end of file diff --git a/docs/en/getting_started.rst b/docs/en/getting_started.rst index 6b2d4aca959..9267f1b427f 100644 --- a/docs/en/getting_started.rst +++ b/docs/en/getting_started.rst @@ -41,6 +41,8 @@ ESP32 Yes Yes `ESP32`_ ESP32-S2 Yes Yes `ESP32-S2`_ ESP32-C3 Yes Yes `ESP32-C3`_ ESP32-S3 Yes Yes `ESP32-S3`_ +ESP32-C6 No Yes `ESP32-C6`_ +ESP32-H2 No Yes `ESP32-H2`_ ======== ====== =========== =================================== See `Boards `_ for more details about ESP32 development boards. diff --git a/docs/en/index.rst b/docs/en/index.rst index 3ed77588b26..f7f93f9cc92 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -16,6 +16,7 @@ Here you will find all the relevant information about the project based on the { Guides Tutorials Advanced Utilities + Migration Guides FAQ Troubleshooting Contributing diff --git a/docs/en/installing.rst b/docs/en/installing.rst index 5f29ce10028..3acabd5505c 100644 --- a/docs/en/installing.rst +++ b/docs/en/installing.rst @@ -73,6 +73,8 @@ Installing using PlatformIO PlatformIO is a professional collaborative platform for embedded development. It has out-of-the-box support for ESP32 SoCs and allows working with Arduino ESP32 as well as ESP-IDF from Espressif without changing your development environment. PlatformIO includes lots of instruments for the most common development tasks such as debugging, unit testing, and static code analysis. +.. warning:: Integration of the Arduino Core ESP32 project in PlatformIO is maintained by PlatformIO developers. Arduino Core ESP32 Project Team cannot support PlatformIO-specific issues. Please report these issues in official `PlatformIO repositories `_. + A detailed overview of the PlatformIO ecosystem and its philosophy can be found in `the official documentation `_. PlatformIO can be used in two flavors: diff --git a/docs/source/migration_guides/2.x_to_3.0.rst b/docs/en/migration_guides/2.x_to_3.0.rst similarity index 100% rename from docs/source/migration_guides/2.x_to_3.0.rst rename to docs/en/migration_guides/2.x_to_3.0.rst diff --git a/docs/source/migration_guides/migration_guides.rst b/docs/en/migration_guides/migration_guides.rst similarity index 100% rename from docs/source/migration_guides/migration_guides.rst rename to docs/en/migration_guides/migration_guides.rst diff --git a/docs/en/ota_web_update.rst b/docs/en/ota_web_update.rst index 17cbe3583f5..179101770a0 100644 --- a/docs/en/ota_web_update.rst +++ b/docs/en/ota_web_update.rst @@ -8,6 +8,9 @@ OTAWebUpdate is done with a web browser that can be useful in the following typi - after deployment if user is unable to expose Firmware for OTA from external update server - provide updates after deployment to small quantity of modules when setting an update server is not practicable +For more information about the update process, please refer to the `OTA API reference `_ +section of the ESP-IDF documentation. + Requirements ------------ diff --git a/docs/source/api/adc.rst b/docs/source/api/adc.rst deleted file mode 100644 index 8ab252e181b..00000000000 --- a/docs/source/api/adc.rst +++ /dev/null @@ -1,281 +0,0 @@ -### -ADC -### - -About ------ - -ADC (analog to digital converter) is a very common peripheral used to convert an analog signal such as voltage -to a digital form so that it can be read and processed by a microcontroller. - -ADCs are very useful in control and monitoring applications since most sensors -(e.g., temperature, pressure, force) produce analogue output voltages. - -.. note:: Each SoC or module has a different number of ADC's with a different number of channels and pins available. Refer to datasheet of each board for more info. - -Arduino-ESP32 ADC API ---------------------- - -ADC OneShot mode -**************** - - -The ADC OneShot mode API is fully compatible with Arduino's ``analogRead`` function. -When you call the ``analogRead`` or ``analogReadMillivolts`` function, it returns the result of a single conversion on the requested pin. - -analogRead -^^^^^^^^^^ - -This function is used to get the ADC raw value for a given pin/ADC channel. - -.. code-block:: arduino - - uint16_t analogRead(uint8_t pin); - -* ``pin`` GPIO pin to read analog value - -This function will return analog raw value (non-calibrated). - -analogReadMillivolts -^^^^^^^^^^^^^^^^^^^^ - -This function is used to get ADC raw value for a given pin/ADC channel and convert it to calibrated result in millivolts. - -.. code-block:: arduino - - uint32_t analogReadMilliVolts(uint8_t pin); - -* ``pin`` GPIO pin to read analog value - -This function will return analog value in millivolts (calibrated). - -analogReadResolution -^^^^^^^^^^^^^^^^^^^^ - -This function is used to set the resolution of ``analogRead`` return value. Default is 12 bits (range from 0 to 4095) -for all chips except ESP32S3 where default is 13 bits (range from 0 to 8191). -When different resolution is set, the values read will be shifted to match the given resolution. - -Range is 1 - 16 .The default value will be used, if this function is not used. - -.. note:: For the ESP32, the resolution is between 9 to12 and it will change the ADC hardware resolution. Else value will be shifted. - -.. code-block:: arduino - - void analogReadResolution(uint8_t bits); - -* ``bits`` sets analog read resolution - -analogSetAttenuation -^^^^^^^^^^^^^^^^^^^^ - -This function is used to set the attenuation for all channels. - -Input voltages can be attenuated before being input to the ADCs. -There are 4 available attenuation options, the higher the attenuation is, the higher the measurable input voltage could be. - -The measurable input voltage differs for each chip, see table below for detailed information. - -.. tabs:: - - .. tab:: ESP32 - - ===================== =========================================== - Attenuation Measurable input voltage range - ===================== =========================================== - ``ADC_ATTEN_DB_0`` 100 mV ~ 950 mV - ``ADC_ATTEN_DB_2_5`` 100 mV ~ 1250 mV - ``ADC_ATTEN_DB_6`` 150 mV ~ 1750 mV - ``ADC_ATTEN_DB_11`` 150 mV ~ 3100 mV - ===================== =========================================== - - .. tab:: ESP32-S2 - - ===================== =========================================== - Attenuation Measurable input voltage range - ===================== =========================================== - ``ADC_ATTEN_DB_0`` 0 mV ~ 750 mV - ``ADC_ATTEN_DB_2_5`` 0 mV ~ 1050 mV - ``ADC_ATTEN_DB_6`` 0 mV ~ 1300 mV - ``ADC_ATTEN_DB_11`` 0 mV ~ 2500 mV - ===================== =========================================== - - .. tab:: ESP32-C3 - - ===================== =========================================== - Attenuation Measurable input voltage range - ===================== =========================================== - ``ADC_ATTEN_DB_0`` 0 mV ~ 750 mV - ``ADC_ATTEN_DB_2_5`` 0 mV ~ 1050 mV - ``ADC_ATTEN_DB_6`` 0 mV ~ 1300 mV - ``ADC_ATTEN_DB_11`` 0 mV ~ 2500 mV - ===================== =========================================== - - .. tab:: ESP32-S3 - - ===================== =========================================== - Attenuation Measurable input voltage range - ===================== =========================================== - ``ADC_ATTEN_DB_0`` 0 mV ~ 950 mV - ``ADC_ATTEN_DB_2_5`` 0 mV ~ 1250 mV - ``ADC_ATTEN_DB_6`` 0 mV ~ 1750 mV - ``ADC_ATTEN_DB_11`` 0 mV ~ 3100 mV - ===================== =========================================== - -.. code-block:: arduino - - void analogSetAttenuation(adc_attenuation_t attenuation); - -* ``attenuation`` sets the attenuation. - -analogSetPinAttenuation -^^^^^^^^^^^^^^^^^^^^^^^ - -This function is used to set the attenuation for a specific pin/ADC channel. For more information refer to `analogSetAttenuation`_. - -.. code-block:: arduino - - void analogSetPinAttenuation(uint8_t pin, adc_attenuation_t attenuation); - -* ``pin`` selects specific pin for attenuation settings. -* ``attenuation`` sets the attenuation. - -analogSetWidth -^^^^^^^^^^^^^^ - -.. note:: This function is only available for ESP32 chip. - -This function is used to set the hardware sample bits and read resolution. -Default is 12bit (0 - 4095). -Range is 9 - 12. - -.. code-block:: arduino - - void analogSetWidth(uint8_t bits); - -ADC Continuous mode -******************* - -ADC Continuous mode is an API designed for performing analog conversions on multiple pins in the background, -with the feature of receiving a callback upon completion of these conversions to access the results. - -This API allows you to specify the desired number of conversions per pin within a single cycle, along with its corresponding sampling rate. -The outcome of the ``analogContinuousRead`` function is an array of ``adc_continuous_data_t`` structures. -These structures hold both the raw average value and the average value in millivolts for each pin. - -analogContinuous -^^^^^^^^^^^^^^^^ - -This function is used to configure ADC continuous peripheral on selected pins. - -.. code-block:: arduino - - bool analogContinuous(uint8_t pins[], size_t pins_count, uint32_t conversions_per_pin, uint32_t sampling_freq_hz, void (*userFunc)(void)); - -* ``pins[]`` array of pins to be set up -* ``pins_count`` count of pins in array -* ``conversions_per_pin`` sets how many conversions per pin will run each ADC cycle -* ``sampling_freq_hz`` sets sampling frequency of ADC in Hz -* ``userFunc`` sets callback function to be called after adc conversion is done (can be set to ``NULL``) - -This function will return ``true`` if configuration is successful. -If ``false`` is returned, error occurs and ADC continuous was not configured. - -analogContinuousRead -^^^^^^^^^^^^^^^^^^^^ - -This function is used to read ADC continuous data to the result buffer. The result buffer is an array of ``adc_continuos_data_t``. - -.. code-block:: arduino - - typedef struct { - uint8_t pin; /*! AnalogReadSerial. - -.. literalinclude:: ../../../libraries/ESP32/examples/AnalogRead/AnalogRead.ino - :language: arduino - -Here is an example of how to use the ADC in Continuous mode. - -.. literalinclude:: ../../../libraries/ESP32/examples/AnalogReadContinuous/AnalogReadContinuous.ino - :language: arduino diff --git a/docs/source/api/wifi.rst b/docs/source/api/wifi.rst deleted file mode 100644 index 1fd5651f38b..00000000000 --- a/docs/source/api/wifi.rst +++ /dev/null @@ -1,675 +0,0 @@ -######### -Wi-Fi API -######### - -About ------ - -The Wi-Fi API provides support for the 802.11b/g/n protocol driver. This API includes: - -* Station mode (STA mode or Wi-Fi client mode). ESP32 connects to an access point - -* AP mode (aka Soft-AP mode or Access Point mode). Devices connect to the ESP32 - -* Security modes (WPA2, WPA3 etc.) - -* Scanning for access points - -Working as AP -************* - -In this mode, the ESP32 is configured as an Access Point (AP) and it's capable of receiving incoming connections from other devices (stations) by providing -a Wi-Fi network. - -.. figure:: ../_static/wifi_esp32_ap.png - :align: center - :width: 520 - :figclass: align-center - -This mode can be used for serving an HTTP or HTTPS server inside the ESP32, for example. - -Working as STA -************** - -The STA mode is used to connect the ESP32 to a Wi-Fi network, provided by an Access Point. - -.. figure:: ../_static/wifi_esp32_sta.png - :align: center - :width: 520 - :figclass: align-center - -This is the mode to be used if you want to connect your project to the Internet. - -API Description ---------------- - -Here is the description of the WiFi API. - -Common API ----------- - -Here are the common APIs that are used for both modes, AP and STA. - -onEvent (and removeEvent) -************************* - -Registers a caller-supplied function to be called when WiFi events -occur. Several forms are available. - -Function pointer callback taking the event ID: - -.. code-block:: arduino - - typedef void (*WiFiEventCb)(arduino_event_id_t); - wifi_event_id_t onEvent(WiFiEventCb, arduino_event_id_t = ARDUINO_EVENT_MAX); - -Function pointer callback taking an event-ID-and-info struct: - -.. code-block:: arduino - - typedef struct{ - arduino_event_id_t event_id; - arduino_event_info_t event_info; - } arduino_event_t; - - typedef void (*WiFiEventSysCb)(arduino_event_t *); - wifi_event_id_t onEvent(WiFiEventSysCb, arduino_event_id_t = ARDUINO_EVENT_MAX); - -Callback using ``std::function`` taking event ID and info separately: - -.. code-block:: arduino - - typedef std::function WiFiEventFuncCb; - wifi_event_id_t onEvent(WiFiEventFuncCb, arduino_event_id_t = ARDUINO_EVENT_MAX); - -A similar set of functions are available to remove callbacks: - -.. code-block:: arduino - - void removeEvent(WiFiEventCb, arduino_event_id_t = ARDUINO_EVENT_MAX); - void removeEvent(WiFiEventSysCb, arduino_event_id_t = ARDUINO_EVENT_MAX); - void removeEvent(wifi_event_id_t = ARDUINO_EVENT_MAX); - -In all cases, the subscribing function accepts an optional event type to -invoke the callback only for that specific event; with the default -``ARDUINO_EVENT_MAX``, the callback will be invoked for all WiFi events. - -Any callback function is given the event type in a parameter. -Some of the possible callback function formats also take an -``arduino_event_info_t`` (or use ``arduino_event_t`` which includes both -ID and info) which is a union of structs with additional information -about different event types. - -See -`WiFiGeneric.h `_ -for the list of event types and "info" substructures, and also see a full -example of event handling: `events example`_. - -.. warning:: - - Event callback functions are invoked on a separate - `thread `_ - (`FreeRTOS task `_) - independent of the main application thread that runs ``setup()`` and - ``loop()``. Callback functions must therefore be - `thread-safe `_; - they must not access shared/global variables directly without locking, - and must only call similarly thread-safe functions. - - Some core operations like ``Serial.print()`` are thread-safe but many - functions are not. Notably, ``WiFi.onEvent()`` and ``WiFi.removeEvent()`` - are not thread-safe and should never be invoked from a callback thread. - -setHostname (and getHostname) -***************************** - -Sets the name the DHCP client uses to identify itself. In a typical network -setup this will be the name that shows up in the Wi-Fi router's device list. -The hostname must be no longer than 32 characters. - -.. code-block:: arduino - - setHostname(const char *hostname); - -If the hostname is never specified, a default one will be assigned based -on the chip type and MAC address. The current hostname (default or custom) -may be retrieved: - -.. code-block:: arduino - - const char *getHostname(); - -.. warning:: - - The ``setHostname()`` function must be called BEFORE WiFi is started with - ``WiFi.begin()``, ``WiFi.softAP()``, ``WiFi.mode()``, or ``WiFi.run()``. - To change the name, reset WiFi with ``WiFi.mode(WIFI_MODE_NULL)``, - then proceed with ``WiFi.setHostname(...)`` and restart WiFi from scratch. - -useStaticBuffers -**************** - -This function is used to set the memory allocation mode for the Wi-Fi buffers. - -.. code-block:: arduino - - static void useStaticBuffers(bool bufferMode); - -* Set ``true`` to use the Wi-Fi buffers memory allocation as **static**. -* Set ``false`` to set the buffers memory allocation to **dynamic**. - -The use of dynamic allocation is recommended to save memory and reduce resources usage. However, the dynamic performs slightly slower than the static allocation. -Use static allocation if you want to have more performance and if your application is multi-tasking. - -By default, the memory allocation will be set to **dynamic** if this function is not being used. - -setDualAntennaConfig -******************** - -Configures the Dual antenna functionallity. This function should be used only on the **ESP32-WROOM-DA** module or any other ESP32 with RF switch. - -.. code-block:: arduino - - bool setDualAntennaConfig(uint8_t gpio_ant1, uint8_t gpio_ant2, wifi_rx_ant_t rx_mode, wifi_tx_ant_t tx_mode); - - -* ``gpio_ant1`` Configure the GPIO number for the antenna 1 connected to the RF switch (default ``GPIO2`` on ESP32-WROOM-DA) -* ``gpio_ant2`` Configure the GPIO number for the antenna 2 connected to the RF switch (default ``GPIO25`` on ESP32-WROOM-DA) -* ``rx_mode`` Set the RX antenna mode. See wifi_rx_ant_t for the options. -* ``tx_mode`` Set the TX antenna mode. See wifi_tx_ant_t for the options. - -Return ``true`` if the configuration was successful. - -For the ``rx_mode`` you can use the following configuration: - -* ``WIFI_RX_ANT0`` Selects the antenna 1 for all RX activity. -* ``WIFI_RX_ANT1`` Selects the antenna 2 for all RX activity. -* ``WIFI_RX_ANT_AUTO`` Selects the antenna for RX automatically. - -For the ``tx_mode`` you can use the following configuration: - -* ``WIFI_TX_ANT0`` Selects the antenna 1 for all TX activity. -* ``WIFI_TX_ANT1`` Selects the antenna 2 for all TX activity. -* ``WIFI_TX_ANT_AUTO`` Selects the antenna for TX automatically. - -WiFiAP ------- - -The ``WiFiAP`` is used to configure and manage the Wi-Fi as an Access Point. This is where you can find the related functions for the AP. - -Basic Usage -*********** - -To start the Wi-Fi as an Access Point. - -.. code-block:: arduino - - WiFi.softAP(ssid, password); - -Please see the full WiFiAP example in: `ap example`_. - -AP Configuration ----------------- - -softAP -****** - -Use the function ``softAP`` to configure the Wi-Fi AP characteristics: - -.. code-block:: arduino - - bool softAP(const char* ssid, const char* passphrase = NULL, int channel = 1, int ssid_hidden = 0, int max_connection = 4, bool ftm_responder = false); - -Where: - -* ``ssid`` sets the Wi-Fi network SSID. -* ``passphrase`` sets the Wi-Fi network password. If the network is open, set as ``NULL``. -* ``channel`` configures the Wi-Fi channel. -* ``ssid_hidden`` sets the network as hidden. -* ``max_connection`` sets the maximum number of simultaneous connections. The default is 4. -* ``ftm_responder`` sets the Wi-Fi FTM responder feature. **Only for ESP32-S2 and ESP32-C3 SoC!** - -Return ``true`` if the configuration was successful. - -softAPConfig -************ - -Function used to configure the IP as static (fixed) as well as the gateway and subnet. - -.. code-block:: arduino - - bool softAPConfig(IPAddress local_ip, IPAddress gateway, IPAddress subnet); - -Where: - -* ``local_ip`` sets the local IP address. -* ``gateway`` sets the gateway IP. -* ``subnet`` sets the subnet mask. - -The function will return ``true`` if the configuration is successful. - -AP Connection -------------- - -softAPdisconnect -**************** - -Function used to force the AP disconnection. - -.. code-block:: arduino - - bool softAPdisconnect(bool wifioff = false); - -Where: - -* ``wifioff`` sets the Wi-Fi off if ``true``. - -The function will return ``true`` if the configuration is successful. - - -softAPgetStationNum -******************* - -This function returns the number of clients connected to the AP. - -.. code-block:: arduino - - uint8_t softAPgetStationNum(); - -softAPIP -******** - -Function to get the AP IPv4 address. - -.. code-block:: arduino - - IPAddress softAPIP(); - -The function will return the AP IP address in ``IPAddress`` format. - -softAPBroadcastIP -***************** - -Function to get the AP IPv4 broadcast address. - -.. code-block:: arduino - - IPAddress softAPBroadcastIP(); - -The function will return the AP broadcast address in ``IPAddress`` format. - -softAPNetworkID -*************** - -Get the softAP network ID. - -.. code-block:: arduino - - IPAddress softAPNetworkID(); - -The function will return the AP network address in ``IPAddress`` format. - -softAPSubnetCIDR -**************** - -Get the softAP subnet CIDR. - -.. code-block:: arduino - - uint8_t softAPSubnetCIDR(); - -softAPSubnetMask -**************** - -Get the softAP subnet mask. - -.. code-block:: arduino - - IPAddress softAPSubnetMask(); - -softAPenableIpV6 -**************** - -Function used to enable the IPv6 support. - -.. code-block:: arduino - - bool softAPenableIpV6(); - -The function will return ``true`` if the configuration is successful. - -softAPIPv6 -********** - -Function to get the IPv6 address. - -.. code-block:: arduino - - IPv6Address softAPIPv6(); - -The function will return the AP IPv6 address in ``IPv6Address`` format. - -softAPgetHostname -***************** - -Function to get the AP hostname. - -.. code-block:: arduino - - const char * softAPgetHostname(); - -softAPsetHostname -***************** - -Function to set the AP hostname. - -.. code-block:: arduino - - bool softAPsetHostname(const char * hostname); - -Where: - -* ``hostname`` sets the device hostname. - -The function will return ``true`` if the configuration is successful. - - -softAPmacAddress -**************** - -Function to define the AP MAC address. - -.. code-block:: arduino - - uint8_t* softAPmacAddress(uint8_t* mac); - -Where: - -* ``mac`` sets the new MAC address. - -Function to get the AP MAC address. - -.. code-block:: arduino - - String softAPmacAddress(void); - -softAPSSID -********** - -Function to get the AP SSID. - -.. code-block:: arduino - - String softAPSSID(void) const; - -Returns the AP SSID. - -WiFiSTA -------- - -The ``WiFiSTA`` is used to configure and manage the Wi-Fi as Station. The related functions for the STA are here. - -Basic Usage -*********** - -The following code shows the basic usage of the WifiSTA functionality. - -.. code-block:: arduino - - WiFi.begin(ssid, password); - -Where the ``ssid`` and ``password`` are from the network you want to connect the ESP32. - -To check if the connection is successful, you can use: - -.. code-block:: arduino - - while (WiFi.status() != WL_CONNECTED) { - delay(500); - Serial.print("."); - } - -After a successful connection, you can print the IP address given by the network. - -.. code-block:: arduino - - Serial.println("IP address: "); - Serial.println(WiFi.localIP()); - -Please see the full example of the WiFiSTA in: `sta example`_. - -STA Configuration ------------------ - -begin -***** - -- Functions ``begin`` are used to configure and start the Wi-Fi. - -.. code-block:: arduino - - wl_status_t begin(const char* ssid, const char *passphrase = NULL, int32_t channel = 0, const uint8_t* bssid = NULL, bool connect = true); - -Where: - -* ``ssid`` sets the AP SSID. -* ``passphrase`` sets the AP password. Set as ``NULL`` for open networks. -* ``channel`` sets the Wi-Fi channel. -* ``uint8_t* bssid`` sets the AP BSSID. -* ``connect`` sets ``true`` to connect to the configured network automatically. - -.. code-block:: arduino - - wl_status_t begin(char* ssid, char *passphrase = NULL, int32_t channel = 0, const uint8_t* bssid = NULL, bool connect = true); - -Where: - -* ``ssid`` sets the AP SSID. -* ``passphrase`` sets the AP password. Set as ``NULL`` for open networks. -* ``channel`` sets the Wi-Fi channel. -* ``bssid`` sets the AP BSSID. -* ``connect`` sets ``true`` to connect to the configured network automatically. - -Function to start the connection after being configured. - -.. code-block:: arduino - - wl_status_t begin(); - -config -****** - -Function ``config`` is used to configure Wi-Fi. After configuring, you can call function ``begin`` to start the Wi-Fi process. - -.. code-block:: arduino - - bool config(IPAddress local_ip, IPAddress gateway, IPAddress subnet, IPAddress dns1 = (uint32_t)0x00000000, IPAddress dns2 = (uint32_t)0x00000000); - -Where: - -* ``local_ip`` sets the local IP. -* ``gateway`` sets the gateway IP. -* ``subnet`` sets the subnet mask. -* ``dns1`` sets the DNS. -* ``dns2`` sets the DNS alternative option. - -The function will return ``true`` if the configuration is successful. - -The ``IPAddress`` format is defined by 4 bytes as described here: - -.. code-block:: arduino - - IPAddress(uint8_t first_octet, uint8_t second_octet, uint8_t third_octet, uint8_t fourth_octet); - -Example: - -.. code-block:: arduino - - IPAddress local_ip(192, 168, 10, 20); - -See the ``WiFiClientStaticIP.ino`` for more details on how to use this feature. - -STA Connection --------------- - -reconnect -********* - -Function used to reconnect the Wi-Fi connection. - -.. code-block:: arduino - - bool reconnect(); - -disconnect -********** - -Function to force disconnection. - -.. code-block:: arduino - - bool disconnect(bool wifioff = false, bool eraseap = false); - -Where: - -* ``wifioff`` use ``true`` to turn the Wi-Fi radio off. -* ``eraseap`` use ``true`` to erase the AP configuration from the NVS memory. - -The function will return ``true`` if the configuration is successful. - -isConnected -*********** - -Function used to get the connection state. - -.. code-block:: arduino - - bool isConnected(); - -Return the connection state. - -setAutoConnect -************** - -Function is deprecated. - -getAutoConnect -************** - -Function is deprecated. - -setAutoReconnect -**************** - -Function used to set the automatic reconnection if the connection is lost. - -.. code-block:: arduino - - bool setAutoReconnect(bool autoReconnect); - -Where: - -* ``autoConnect`` is set to ``true`` to enable this option. - -getAutoReconnect -**************** - -Function used to get the automatic reconnection if the connection is lost. - -.. code-block:: arduino - - bool getAutoReconnect(); - -The function will return ``true`` if this setting is enabled. - -setMinSecurity -************** - -Function used to set the minimum security for AP to be considered connectable. - -.. code-block:: arduino - - bool setMinSecurity(wifi_auth_mode_t minSecurity); - -Where: - -* ``minSecurity`` is the minimum security for AP to be considered connectable. Default is ``WIFI_AUTH_WPA2_PSK``. - -WiFiMulti ---------- - -The ``WiFiMulti`` allows you to add more than one option for the AP connection while running as a station. - -To add the AP, use the following function. You can add multiple AP's and this library will handle the connection. - -.. code-block:: arduino - - bool addAP(const char* ssid, const char *passphrase = NULL); - -After adding the AP's, run by the following function. - -.. code-block:: arduino - - uint8_t run(uint32_t connectTimeout=5000); - -To see how to use the ``WiFiMulti``, take a look at the ``WiFiMulti.ino`` example available. - -WiFiScan --------- - -To perform the Wi-Fi scan for networks, you can use the following functions: - -Start scan WiFi networks available. - -.. code-block:: arduino - - int16_t scanNetworks(bool async = false, bool show_hidden = false, bool passive = false, uint32_t max_ms_per_chan = 300, uint8_t channel = 0); - -Called to get the scan state in Async mode. - -.. code-block:: arduino - - int16_t scanComplete(); - -Delete last scan result from RAM. - -.. code-block:: arduino - - void scanDelete(); - -Loads all infos from a scanned wifi in to the ptr parameters. - -.. code-block:: arduino - - bool getNetworkInfo(uint8_t networkItem, String &ssid, uint8_t &encryptionType, int32_t &RSSI, uint8_t* &BSSID, int32_t &channel); - -To see how to use the ``WiFiScan``, take a look at the ``WiFiScan.ino`` example available. - -Examples --------- - -`Complete list of WiFi examples `_. - -.. _ap example: - -Wi-Fi AP Example -**************** - -.. literalinclude:: ../../../libraries/WiFi/examples/WiFiAccessPoint/WiFiAccessPoint.ino - :language: arduino - -.. _sta example: - -Wi-Fi STA Example -***************** - -.. literalinclude:: ../../../libraries/WiFi/examples/WiFiClient/WiFiClient.ino - :language: arduino - -.. _events example: - -Wi-Fi Events Example -******************** - -.. literalinclude:: ../../../libraries/WiFi/examples/WiFiClientEvents/WiFiClientEvents.ino - :language: arduino diff --git a/docs/source/boards/boards.rst b/docs/source/boards/boards.rst deleted file mode 100644 index 6214fe4ebd1..00000000000 --- a/docs/source/boards/boards.rst +++ /dev/null @@ -1,120 +0,0 @@ -###### -Boards -###### - -Development Boards ------------------- - -You will need a development board or a custom board with the ESP32 (see Supported SoC's) to start playing. -There is a bunch of different types and models widely available on the Internet. You need to choose one that covers all your requirements. - -To help you on this selection, we point out some facts about choosing the proper boards to help you to save money and time. - -**One ESP32 to rule them all!** - -One important information that usually bring about some confusion is regarding the different models of the ESP32 SoC and modules. - -The ESP32 is divided by family: - -* ESP32 - * Wi-Fi and BLE -* ESP32-S - * Wi-Fi only -* ESP32-C - * Wi-Fi and BLE 5 -* ESP32-H - * BLE and IEEE 802.15.4 - -For each family, we have SoC variants with some differentiation. The differences are more about the embedded flash and its size and the number of the cores (dual or single). - -The modules use the SoC internally, including the external flash, PSRAM (in some models) and other essential electronic components. Essentially, all -modules from the same family use the same SoC. - -.. figure:: ../_static/soc-module.png - :align: center - :width: 250 - :alt: ESP32 SoC and Module (click to enlarge) - :figclass: align-center - -**For example:** - -The SoC partnumber is the ESP32-D0WD-V3 and it's the same SoC used inside of the ESP32-WROVER (with PSRAM) and ESP32-WROOM modules. This means that the -same characteristics are present in both modules' core. - -For more detailed information regarding the SoC's and modules, see the `Espressif Product Selector`_. - -Now that you know that the module can be different but the heart is the same, you can choose your development board. - -Before buying: Keep in mind that for some "must have" features when choosing the best board for your needs: - -- Embedded USB-to-Serial - - This is very convenient for programming and monitoring the logs with the terminal via USB. -- Breadboard friendly - - If you are prototyping, this will be very useful to connect your board directly on the breadboard. -- open-source/open-hardware - - Check if the schematics are available for download. This helps a lot on prototyping. -- Support - - Some of the manufacturers offer a very good level of support, with examples and demo projects. - - -Espressif ---------- - -.. figure:: ../_static/logo_espressif.png - :align: center - :width: 250 - :alt: Espressif Logo - :figclass: align-center - -.. toctree:: - :maxdepth: 1 - - ESP32-DevKitC - ESP32-S2-Saola-1 - ESP32-C3-DevKitM-1 - -.. note:: - Only a few development boards are described on this documentation page. For more information about other Espressif development boards please refer to the `Espressif website `_. - -Third Party ------------ - -Add here the third party boards, listed by vendors. - -.. note:: - All the information must be provided by the vendor. If your favorite board is not here, consider - creating an `issue on GitHub `_ and directly - link/mention the vendor in the issue description. - -LOLIN -***** - -* |board_lolin_d32| -* |board_lolin_d32_pro| - -Generic Vendor -************** - - .. toctree:: - :maxdepth: 1 - - Generic Board Name - - .. note:: - Create one file per board or one file with multiple boards. Do not add board information/description on this file. - -.. include:: ../common/datasheet.inc - -Resources ---------- - -.. _Espressif Systems: https://www.espressif.com -.. _Espressif Product Selector: https://products.espressif.com/ - -.. |board_lolin_d32| raw:: html - - LOLIN D32 - -.. |board_lolin_d32_pro| raw:: html - - LOLIN D32 Pro diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index 47b30b912ed..00000000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,72 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -import os -import sys -# sys.path.insert(0, os.path.abspath('.')) - - -# -- Project information ----------------------------------------------------- - -project = 'Arduino-ESP32' -copyright = '2023, Espressif' -author = 'Espressif' - -# The full version, including alpha/beta/rc tags -release = '2.0.14' - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - 'sphinx_rtd_theme', - 'sphinx_copybutton', - 'sphinx_tabs.tabs' -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' - -# The master toctree document. -master_doc = 'index' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = [] - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "sphinx_rtd_theme" -html_logo = '_static/logo_espressif.png' - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# Style -# pygments_style = "sphinx" - -# Tracking ID for Google Analytics -google_analytics_id = 'G-F58JM78930' diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst deleted file mode 100644 index 3540dda685b..00000000000 --- a/docs/source/getting_started.rst +++ /dev/null @@ -1,155 +0,0 @@ -############### -Getting Started -############### - -About Arduino ESP32 -------------------- - -Welcome to the Arduino ESP32 support documentation! Here you will find important information on how to use the project. - -First Things First ------------------- - -.. note:: - Before continuing, we must be clear that this project is supported by `Espressif Systems`_ and the community. - Everyone is more than welcome to contribute back to this project. - -ESP32 is a single 2.4 GHz Wi-Fi-and-Bluetooth SoC (System On a Chip) designed by `Espressif Systems`_. - -ESP32 is designed for mobile, wearable electronics, and Internet-of-Things (IoT) applications. It features all the state-of-the-art characteristics -of low-power chips, including fine-grained clock gating, multiple power modes,and dynamic power scaling. For instance, in a low-power IoT sensor -hub application scenario, ESP32 is woken-up periodically and only when a specified condition is detected. Low-duty cycle is used to minimize the -amount of energy that the chip expends. - -The output of the power amplifier is also adjustable, thus contributing to an optimal trade-off between communication range, data rate and -power consumption. - -The ESP32 series is available as a chip or module. - - -.. _supported_socs: - -Supported SoC's ---------------- - -Here are the ESP32 series supported by the Arduino-ESP32 project: - -======== ====== =========== =================================== -SoC Stable Development Datasheet -======== ====== =========== =================================== -ESP32 Yes Yes `ESP32`_ -ESP32-S2 Yes Yes `ESP32-S2`_ -ESP32-C3 Yes Yes `ESP32-C3`_ -ESP32-S3 Yes Yes `ESP32-S3`_ -ESP32-C6 No Yes `ESP32-C6`_ -ESP32-H2 No Yes `ESP32-H2`_ -======== ====== =========== =================================== - -See `Boards `_ for more details about ESP32 development boards. - -Arduino Core Reference ----------------------- - -This documentation is built on the ESP32 and we are not going to cover the common Arduino API. To see the Arduino reference documentation, -please consider reading the official documentation. - -Arduino Official Documentation: `Arduino Reference`_. - -Supported Operating Systems ---------------------------- - -+-------------------+-------------------+-------------------+ -| |windows-logo| | |linux-logo| | |macos-logo| | -+-------------------+-------------------+-------------------+ -| Windows | Linux | macOS | -+-------------------+-------------------+-------------------+ - -.. |windows-logo| image:: _static/logo_windows.png -.. |linux-logo| image:: _static/logo_linux.png -.. |macos-logo| image:: _static/logo_macos.png - -Supported IDEs ---------------------------- - -Here is the list of supported IDE for Arduino ESP32 support integration. - -+-------------------+-------------------+ -| |arduino-logo| | |pio-logo| | -+-------------------+-------------------+ -| Arduino IDE | PlatformIO | -+-------------------+-------------------+ - -.. |arduino-logo| image:: _static/logo_arduino.png -.. |pio-logo| image:: _static/logo_pio.png - -See `Installing Guides `_ for more details on how to install the Arduino ESP32 support. - -Support -------- - -This is an open project and it's supported by the community. Fell free to ask for help in one of the community channels. - -Community ---------- - -The Arduino community is huge! You can find a lot of useful content on the Internet. -Here are some community channels where you may find information and ask for some help, if needed. - -- `ESP32 Forum`_: Official Espressif Forum. -- `ESP32 Forum - Arduino`_: Official Espressif Forum for Arduino related discussions. -- `ESP32 Forum - Hardware`_: Official Espressif Forum for Hardware related discussions. -- `Gitter`_ -- `Espressif MCUs (Discord)`_ -- `ESP32 on Reddit`_ - -Issues Reporting ----------------- - -Before opening a new issue, please read this: - -Be sure to search for a similar reported issue. This avoids duplicating or creating noise in the GitHub Issues reporting. -We also have the troubleshooting guide to save your time on the most common issues reported by users. - -For more details about creating new Issue, see the `Issue Template `_. - -If you have any new idea, see the `Feature request Template `_. - -First Steps ------------ - -Here are the first steps to get the Arduino ESP32 support running. - -To install Arduino-ESP32, please see the dedicated section on the Installation guide. We recommend you install it using the boards manager. - -.. toctree:: - :maxdepth: 2 - - How to Install - Development Boards - -Examples --------- - -After installing the toolchain into your environment, you will be able to see all the dedicated examples for the ESP32. These examples are located -in the examples menu or inside each library folder. - - https://github.com/espressif/arduino-esp32/tree/master/libraries - -There is also a `list of examples `_ managed outside of Espressif, so check them out. - -.. include:: common/datasheet.inc - -Resources ---------- - -.. _Espressif Systems: https://www.espressif.com -.. _Espressif Product Selector: https://products.espressif.com/ -.. _Arduino.cc: https://www.arduino.cc/en/Main/Software -.. _Arduino Reference: https://www.arduino.cc/reference/en/ -.. _ESP32 Forum: https://esp32.com -.. _ESP32 Forum - Arduino: https://esp32.com/viewforum.php?f=19 -.. _ESP32 Forum - Hardware: https://esp32.com/viewforum.php?f=12 -.. _Gitter: https://gitter.im/espressif/arduino-esp32 -.. _Adafruit (Discord): https://discord.gg/adafruit -.. _Espressif MCUs (Discord): https://discord.gg/nKxMTnkD -.. _ESP32 on Reddit: https://www.reddit.com/r/esp32 diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index 4016f36f3d4..00000000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,23 +0,0 @@ -############################################# -Welcome to ESP32 Arduino Core's documentation -############################################# - -Here you will find all the relevant information about the project. - -.. note:: - This is a work in progress documentation and we will appreciate your help! We are looking for contributors! - -.. toctree:: - :maxdepth: 1 - :caption: Contents: - - Getting Started - Libraries - Guides - Tutorials - Advanced Utilities - Migration Guides - FAQ - Troubleshooting - Contributing - External Libraries Testing diff --git a/docs/source/installing.rst b/docs/source/installing.rst deleted file mode 100644 index 3b5554baf32..00000000000 --- a/docs/source/installing.rst +++ /dev/null @@ -1,363 +0,0 @@ -########## -Installing -########## - -This guide will show how to install the Arduino-ESP32 support. - -Before Installing ------------------ - -We recommend you install the support using your favorite IDE, but other options are available depending on your operating system. -To install Arduino-ESP32 support, you can use one of the following options. - -Installing using Arduino IDE ----------------------------- - -.. figure:: _static/logo_arduino.png - :align: center - :width: 200 - :figclass: align-center - -This is the way to install Arduino-ESP32 directly from the Arduino IDE. - -.. note:: - For overview of SoC's support, take a look on `Supported Soc's table `_ where you can find if the particular chip is under stable or development release. - -- Stable release link:: - - https://espressif.github.io/arduino-esp32/package_esp32_index.json - -- Development release link:: - - https://espressif.github.io/arduino-esp32/package_esp32_dev_index.json - - -.. note:: - Starting with the Arduino IDE version 1.6.4, Arduino allows installation of third-party platform - packages using Boards Manager. We have packages available for Windows, macOS, and Linux. - -To start the installation process using the Boards Managaer, follow these steps: - -- Install the current upstream Arduino IDE at the 1.8 level or later. The current version is at the `arduino.cc`_ website. - -- Start Arduino and open the Preferences window. - -.. figure:: _static/install_guide_preferences.png - :align: center - :width: 600 - :figclass: align-center - -- Enter one of the release links above into *Additional Board Manager URLs* field. You can add multiple URLs, separating them with commas. - -.. figure:: _static/install_guide_boards_manager_url.png - :align: center - :width: 600 - :figclass: align-center - -- Open Boards Manager from Tools > Board menu and install *esp32* platform (and do not forget to select your ESP32 board from Tools > Board menu after installation). - -.. figure:: _static/install_guide_boards_manager_esp32.png - :align: center - :width: 600 - :figclass: align-center - -- Restart Arduino IDE. - -Installing using PlatformIO ---------------------------- - -.. figure:: _static/logo_pio.png - :align: center - :width: 200 - :figclass: align-center - -PlatformIO is a professional collaborative platform for embedded development. It has out-of-the-box support for ESP32 SoCs and allows working with Arduino ESP32 as well as ESP-IDF from Espressif without changing your development environment. PlatformIO includes lots of instruments for the most common development tasks such as debugging, unit testing, and static code analysis. - -.. warning:: Integration of the Arduino Core ESP32 project in PlatformIO is maintained by PlatformIO developers. Arduino Core ESP32 Project Team cannot support PlatformIO-specific issues. Please report these issues in official `PlatformIO repositories `_. - -A detailed overview of the PlatformIO ecosystem and its philosophy can be found in `the official documentation `_. - -PlatformIO can be used in two flavors: - -- `PlatformIO IDE `_ is a toolset for embedded C/C++ development available on Windows, macOS and Linux platforms - -- `PlatformIO Core (CLI) `_ is a command-line tool that consists of a multi-platform build system, platform and library managers and other integration components. It can be used with a variety of code development environments and allows integration with cloud platforms and web services - -To install PlatformIO, you can follow this Getting Started, provided at `docs.platformio.org`_. - -Using the stable code -********************* - -.. note:: - A detailed overview of supported development boards, examples and frameworks can be found on `the official Espressif32 dev-platform page `_ in the PlatformIO Registry. - -The most reliable and easiest way to get started is to use the latest stable version of the ESP32 development platform that passed all tests/verifications and can be used in production. - -Create a new project and select one of the available boards. You can change after by changing the `platformio.ini `_ file. - -- For ESP32 - -.. code-block:: bash - - [env:esp32dev] - platform = espressif32 - board = esp32dev - framework = arduino - -- For ESP32-S2 (ESP32-S2-Saola-1 board) - -.. code-block:: bash - - [env:esp32-s2-saola-1] - platform = espressif32 - board = esp32-s2-saola-1 - framework = arduino - -- For ESP32-C3 (ESP32-C3-DevKitM-1 board) - -.. code-block:: bash - - [env:esp32-c3-devkitm-1] - platform = espressif32 - board = esp32-c3-devkitm-1 - framework = arduino - -How to update to the latest code -******************************** - -To test the latest Arduino ESP32, you need to change your project *platformio.ini* accordingly. -The following configuration uses the upstream version of the Espressif development platform and the latest Arduino core directly from the Espressif GitHub repository: - -.. code-block:: bash - - [env:esp32-c3-devkitm-1] - platform = https://github.com/platformio/platform-espressif32.git - board = esp32-c3-devkitm-1 - framework = arduino - platform_packages = - framework-arduinoespressif32 @ https://github.com/espressif/arduino-esp32#master - - -To get more information about PlatformIO, see the following links: - -- `PlatformIO Core (CLI) `_ - -- `PlatformIO Home `_ - -- `Tutorials and Examples `_ - -- `Library Management `_ - - -Windows (manual installation) ------------------------------ - -.. warning:: Arduino ESP32 core v2.x.x cannot be used on Windows 8.x x86 (32 bits), Windows 7 or earlier. The Windows 32 bits OS is no longer supported by this toolchain. - - The Arduino ESP32 v1.0.6 still works on WIN32. You might want to install python 3.8.x because it is the latest release supported by Windows 7. - -Steps to install Arduino ESP32 support on Windows: - -**Step 1** - -1. Download and install the latest Arduino IDE ``Windows Installer`` from [arduino.cc](https://www.arduino.cc/en/Main/Software) -2. Download and install Git from [git-scm.com](https://git-scm.com/download/win) -3. Start ``Git GUI`` and do the following steps: - -- Select ``Clone Existing Repository`` - -.. figure:: _static/win-gui-1.png - :align: center - :width: 600 - :figclass: align-center - -- Select source and destination - - Sketchbook Directory: Usually ``C:/Users/[YOUR_USER_NAME]/Documents/Arduino`` and is listed underneath the "Sketchbook location" in Arduino preferences. - - Source Location: ``https://github.com/espressif/arduino-esp32.git`` - - Target Directory: ``[ARDUINO_SKETCHBOOK_DIR]/hardware/espressif/esp32`` - - Click ``Clone`` to start cloning the repository - -**Step 2** - -.. figure:: _static/win-gui-2.png - :align: center - :figclass: align-center - -**Step 3** - -.. figure:: _static/win-gui-3.png - :align: center - :figclass: align-center - -- open a `Git Bash` session pointing to ``[ARDUINO_SKETCHBOOK_DIR]/hardware/espressif/esp32`` and execute ```git submodule update --init --recursive``` -- Open ``[ARDUINO_SKETCHBOOK_DIR]/hardware/espressif/esp32/tools`` and double-click ``get.exe`` - -**Step 4** - -.. figure:: _static/win-gui-4.png - :align: center - :figclass: align-center - -- When ```get.exe``` finishes, you should see the following files in the directory - -**Step 5** - -.. figure:: _static/win-gui-5.png - :align: center - :figclass: align-center - -1. Plug your ESP32 board and wait for the drivers to install (or install manually any that might be required) -2. Start Arduino IDE -3. Select your board in ``Tools > Board`` menu -4. Select the COM port that the board is attached to -5. Compile and upload (You might need to hold the boot button while uploading) - -.. figure:: _static/arduino-ide.png - :align: center - :figclass: align-center - -How to update to the latest code -******************************** - -1. Start ``Git GUI`` and you should see the repository under ``Open Recent Repository``. Click on it! - -.. figure:: _static/win-gui-update-1.png - :align: center - :figclass: align-center - -1. From menu ``Remote`` select ``Fetch from`` > ``origin`` - -.. figure:: _static/win-gui-update-2.png - :align: center - :figclass: align-center - -1. Wait for git to pull any changes and close ``Git GUI`` -2. Open ``[ARDUINO_SKETCHBOOK_DIR]/hardware/espressif/esp32/tools`` and double-click ``get.exe`` - -.. figure:: _static/win-gui-4.png - :align: center - :figclass: align-center - -Linux ------ - -.. figure:: _static/logo_linux.png - :align: center - :width: 200 - :figclass: align-center - -Debian/Ubuntu -************* - -- Install latest Arduino IDE from `arduino.cc`_. - -- Open Terminal and execute the following command (copy -> paste and hit enter): - -.. code-block:: bash - - sudo usermod -a -G dialout $USER && \ - sudo apt-get install git && \ - wget https://bootstrap.pypa.io/get-pip.py && \ - sudo python3 get-pip.py && \ - sudo pip3 install pyserial && \ - mkdir -p ~/Arduino/hardware/espressif && \ - cd ~/Arduino/hardware/espressif && \ - git clone https://github.com/espressif/arduino-esp32.git esp32 && \ - cd esp32/tools && \ - python3 get.py - -- Restart Arduino IDE. - -- If you have Arduino installed to ~/, modify the installation as follows, beginning at `mkdir -p ~/Arduino/hardware`: - -.. code-block:: bash - - cd ~/Arduino/hardware - mkdir -p espressif && \ - cd espressif && \ - git clone https://github.com/espressif/arduino-esp32.git esp32 && \ - cd esp32/tools && \ - python3 get.py - -Fedora -****** - -- Install the latest Arduino IDE from `arduino.cc`_. - -.. note:: - Command ``$ sudo dnf -y install arduino`` will most likely install an older release. - -- Open Terminal and execute the following command (copy -> paste and hit enter): - -.. code-block:: bash - - sudo usermod -a -G dialout $USER && \ - sudo dnf install git python3-pip python3-pyserial && \ - mkdir -p ~/Arduino/hardware/espressif && \ - cd ~/Arduino/hardware/espressif && \ - git clone https://github.com/espressif/arduino-esp32.git esp32 && \ - cd esp32/tools && \ - python get.py - -- Restart Arduino IDE. - -openSUSE -******** - -- Install the latest Arduino IDE from `arduino.cc`_. - -- Open Terminal and execute the following command (copy -> paste and hit enter): - -.. code-block:: bash - - sudo usermod -a -G dialout $USER && \ - if [ `python --version 2>&1 | grep '2.7' | wc -l` = "1" ]; then \ - sudo zypper install git python-pip python-pyserial; \ - else \ - sudo zypper install git python3-pip python3-pyserial; \ - fi && \ - mkdir -p ~/Arduino/hardware/espressif && \ - cd ~/Arduino/hardware/espressif && \ - git clone https://github.com/espressif/arduino-esp32.git esp32 && \ - cd esp32/tools && \ - python get.py - -- Restart Arduino IDE. - -macOS ------ - -- Install the latest Arduino IDE from `arduino.cc`_. - -- Open Terminal and execute the following command (copy -> paste and hit enter): - -.. code-block:: bash - - mkdir -p ~/Documents/Arduino/hardware/espressif && \ - cd ~/Documents/Arduino/hardware/espressif && \ - git clone https://github.com/espressif/arduino-esp32.git esp32 && \ - cd esp32/tools && \ - python get.py - -Where ``~/Documents/Arduino`` represents your sketch book location as per "Arduino" > "Preferences" > "Sketchbook location" (in the IDE once started). Adjust the command above accordingly. - -- If you get the error below, install through the command line dev tools with `xcode-select --install` and try the command above again: - -.. code-block:: bash - - xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun - -- Run the command: - -.. code-block:: bash - - xcode-select --install - -- Try ``python3`` instead of ``python`` if you get the error: ``IOError: [Errno socket error] [SSL: TLSV1_ALERT_PROTOCOL_VERSION] tlsv1 alert protocol version (_ssl.c:590)`` when running ``python get.py`` - -- If you get the following error when running ``python get.py`` urllib.error.URLError: Applications > Python3.6 folder (or any other python version), and run the following scripts: Install Certificates.command and Update Shell Profile.command - -- Restart Arduino IDE. - -.. _Arduino.cc: https://www.arduino.cc/en/Main/Software -.. _docs.platformio.org: https://docs.platformio.org/en/latest/integration/ide/pioide.html diff --git a/docs/source/ota_web_update.rst b/docs/source/ota_web_update.rst deleted file mode 100644 index be0a6d5e263..00000000000 --- a/docs/source/ota_web_update.rst +++ /dev/null @@ -1,79 +0,0 @@ -############## -OTA Web Update -############## - -OTAWebUpdate is done with a web browser that can be useful in the following typical scenarios: - -- Once the application developed and loading directly from Arduino IDE is inconvenient or not possible -- after deployment if user is unable to expose Firmware for OTA from external update server -- provide updates after deployment to small quantity of modules when setting an update server is not practicable - -For more information about the update process, please refer to the `OTA API reference `_ -section of the ESP-IDF documentation. - -Requirements ------------- - -- The ESP and the computer must be connected to the same network - -Implementation --------------- - -The sample implementation has been done using: - -- Example sketch ```OTAWebUpdater.ino```. -- ESP32 Board. - -You can also use another module if it meets Flash chip size of the sketch - -Before you begin, please make sure that you have the following software installed: - -- Arduino IDE -- Host software depending on O/S you use - - `Avahi `_ for Linux - - `Bonjour `_ for Windows - - Mac OSX and iOS - support is already built in / no any extra s/w is required - -Prepare the sketch and configuration for initial upload with a serial port -- Start Arduino IDE and load sketch OTAWebUpdater.ino available under File > Examples > OTAWebUpdater.ino -- Update ssid and pass in the sketch so the module can join your Wi-Fi network -- Open File > Preferences, look for “Show verbose output during:” and check out “compilation” option - -.. figure:: _static/ota_esp32_verbose.png - :align: center - :figclass: align-center - -- Upload sketch (Ctrl+U) -- Now open web browser and enter the url, i.e. http://esp32.local. Once entered, browser should display a form - -.. figure:: _static/ota_esp32_login.png - :align: center - :figclass: align-center - -* username = admin - -* password = admin - -.. note:: - *If entering “http://ESP32.local” does not work, try replacing “ESP32” with module’s IP address. This workaround is useful in case the host software installed does not work*. - -Now click on the Login button and browser will display an upload form - -.. figure:: _static/ota_esp32_upload.png - :align: center - :figclass: align-center - -For Uploading the New Firmware, you need to provide the Binary File of your Code. - -Exporting Binary file of the Firmware (Code) -- Open up the Arduino IDE -- Open up the Code, for Exporting up Binary file -- Now go to Sketch > export compiled Binary - -.. figure:: _static/ota_export_to_binary.png - :align: center - :figclass: align-center - -- Binary file is exported to the same Directory where your code is present - -Once you are comfortable with this procedure, go ahead and modify OTAWebUpdater.ino sketch to print some additional messages and compile it. Then, export the new binary file and upload it using web browser to see entered changes on a Serial Monitor. From 36aaf87d8ae61500796d73e94455a9bf6cbc654e Mon Sep 17 00:00:00 2001 From: pedrominatel Date: Thu, 7 Dec 2023 10:28:15 +0800 Subject: [PATCH 10/21] Fixed the path for the ResetReason example --- docs/en/api/reset_reason.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/api/reset_reason.rst b/docs/en/api/reset_reason.rst index 49bf9397797..006c2c1d530 100644 --- a/docs/en/api/reset_reason.rst +++ b/docs/en/api/reset_reason.rst @@ -15,5 +15,5 @@ To get started with Reset Reason, you can try: Reset Reason ************ -.. literalinclude:: ../../../libraries/ESP32/examples/ResetReason/ResetReason.ino +.. literalinclude:: ../../../libraries/ESP32/examples/ResetReason/ResetReason/ResetReason.ino :language: arduino \ No newline at end of file From 9c8ebf55d98a79265b351216cc315de9291e83e7 Mon Sep 17 00:00:00 2001 From: pedrominatel Date: Thu, 7 Dec 2023 10:37:49 +0800 Subject: [PATCH 11/21] Added new releases to the Arduino versions file --- docs/_static/arduino_versions.js | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/_static/arduino_versions.js b/docs/_static/arduino_versions.js index 5d6e2d1451d..628368db213 100644 --- a/docs/_static/arduino_versions.js +++ b/docs/_static/arduino_versions.js @@ -4,18 +4,16 @@ var DOCUMENTATION_VERSIONS = { }, VERSIONS: [ { name: "latest", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3", "esp32h2", "esp32c6" ] }, + // 2.0.14 + { name: "release-3.0.0-alpha1", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3", "esp32h2", "esp32c6" ] }, + // 2.0.14 + { name: "release-3.0.0-alpha1", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3", "esp32h2", "esp32c6" ] }, + // 2.0.14 + { name: "release-3.0.0-alpha1", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3", "esp32h2", "esp32c6" ] }, + // 2.0.14 + { name: "release-2.0.14", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3" ] }, // 2.0.13 { name: "release-2.0.13", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3" ] }, - // 2.0.12 - { name: "release-2.0.12", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3" ] }, - // 2.0.11 - { name: "release-2.0.11", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3" ] }, - // 2.0.10 - { name: "release-2.0.10", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3" ] }, - // 2.0.9 - { name: "release-2.0.9", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3" ] }, - // 2.0.8 - { name: "release-2.0.8", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3" ] }, ], IDF_TARGETS: [ { text: "ESP32", value: "esp32"}, From 4b94eadfb69266ed4166faa52e8cd5b6e7ea7d8b Mon Sep 17 00:00:00 2001 From: pedrominatel Date: Thu, 7 Dec 2023 12:32:03 +0800 Subject: [PATCH 12/21] Fixed the JSON wrong link --- docs/en/external_libraries_test.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/external_libraries_test.rst b/docs/en/external_libraries_test.rst index 0d7da671cd2..0a5a34a9e1a 100644 --- a/docs/en/external_libraries_test.rst +++ b/docs/en/external_libraries_test.rst @@ -129,4 +129,4 @@ In the table the results are in order ``BEFORE -> AFTER``. :class: no-scaled-link .. _LIBRARIES_TEST.md: https://github.com/espressif/arduino-esp32/blob/gh-pages/LIBRARIES_TEST.md -.. _lib.json: https://github.com/espressif/arduino-esp32/.github/workflow/lib.json \ No newline at end of file +.. _lib.json: https://github.com/espressif/arduino-esp32/blob/master/.github/workflows/lib.json From a19317b6b14bb49329f39a495854aa565507ce01 Mon Sep 17 00:00:00 2001 From: pedrominatel Date: Thu, 7 Dec 2023 18:26:16 +0800 Subject: [PATCH 13/21] Removed the version and target selection for now --- .github/workflows/docs.yml | 2 +- .github/workflows/docs_deploy.yml | 19 +++++++---- docs/_static/arduino_versions.js | 10 ------ docs/conf_common.py | 54 +++++++++++++++---------------- docs/en/index.rst | 2 +- 5 files changed, 42 insertions(+), 45 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index e0dc48653ef..2ca6b0a3cad 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -36,7 +36,7 @@ jobs: # Update the path to include them and run. cd ./docs PATH=/home/runner/.local/bin:$PATH pip3 install -r requirements.txt --prefer-binary - PATH=/home/runner/.local/bin:$PATH SPHINXOPTS="-W" build-docs -l en -t esp32 esp32s2 esp32s3 esp32c6 esp32h2 + PATH=/home/runner/.local/bin:$PATH SPHINXOPTS="-W" build-docs -l en - name: Archive Docs uses: actions/upload-artifact@v2 with: diff --git a/.github/workflows/docs_deploy.yml b/.github/workflows/docs_deploy.yml index 282ab264a16..16d7408a4e4 100644 --- a/.github/workflows/docs_deploy.yml +++ b/.github/workflows/docs_deploy.yml @@ -1,16 +1,15 @@ name: Documentation Deploy CI +// Deploy to production on each merge to master on: - workflow_dispatch: - release: - types: - - created + push: + branches: + - master paths: - 'docs/**' - '.github/workflows/docs_deploy.yml' jobs: - deploy-preview-docs: name: Deploy Documentation runs-on: ubuntu-22.04 @@ -26,8 +25,16 @@ jobs: python-version: '3.10' - name: Deploy Preview env: + # Deploy to production server + # DOCS_BUILD_DIR: "./docs/_build/" + # DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_DEPLOY_KEY }} + # DOCS_DEPLOY_SERVER: ${{ secrets.DOCS_SERVER }} + # DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_SERVER_USER }} + # DOCS_DEPLOY_PATH: ${{ secrets.DOCS_PATH }} + # DOCS_DEPLOY_URL_BASE: ${{ secrets.DOCS_URL }} + # Deploy to preview server DOCS_BUILD_DIR: "./docs/_build/" - DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_DEPLOY_KEY }} + DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_PREV_DEPLOY_KEY }} DOCS_DEPLOY_SERVER: ${{ secrets.DOCS_PREV_SERVER }} DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_PREV_SERVER_USER }} DOCS_DEPLOY_PATH: ${{ secrets.DOCS_PREV_PATH }} diff --git a/docs/_static/arduino_versions.js b/docs/_static/arduino_versions.js index 628368db213..825bc0cbc27 100644 --- a/docs/_static/arduino_versions.js +++ b/docs/_static/arduino_versions.js @@ -4,16 +4,6 @@ var DOCUMENTATION_VERSIONS = { }, VERSIONS: [ { name: "latest", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3", "esp32h2", "esp32c6" ] }, - // 2.0.14 - { name: "release-3.0.0-alpha1", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3", "esp32h2", "esp32c6" ] }, - // 2.0.14 - { name: "release-3.0.0-alpha1", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3", "esp32h2", "esp32c6" ] }, - // 2.0.14 - { name: "release-3.0.0-alpha1", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3", "esp32h2", "esp32c6" ] }, - // 2.0.14 - { name: "release-2.0.14", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3" ] }, - // 2.0.13 - { name: "release-2.0.13", has_targets: true, supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c3" ] }, ], IDF_TARGETS: [ { text: "ESP32", value: "esp32"}, diff --git a/docs/conf_common.py b/docs/conf_common.py index ded9c5673cb..eceaebb8a25 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -4,14 +4,14 @@ languages = ["en"] -idf_targets = [ - "esp32", - "esp32s2", - "esp32s3", - "esp32c3", - "esp32c6", - "esp32h2", -] +# idf_targets = [ +# "esp32", +# "esp32s2", +# "esp32s3", +# "esp32c3", +# "esp32c6", +# "esp32h2", +# ] # link roles config github_repo = "espressif/arduino-esp32" @@ -29,26 +29,26 @@ 'esp_docs.esp_extensions.dummy_build_system', ] -ESP32_DOCS = [ - "index.rst", -] - -ESP32S2_DOCS = ESP32_DOCS -ESP32C3_DOCS = ESP32S2_DOCS -ESP32S3_DOCS = ESP32S2_DOCS -ESP32C6_DOCS = ESP32S2_DOCS -ESP32H2_DOCS = ESP32S2_DOCS - -conditional_include_dict = { - "esp32": ESP32_DOCS, - "esp32s2": ESP32S2_DOCS, - "esp32c3": ESP32C3_DOCS, - "esp32s3": ESP32S3_DOCS, - "esp32c6": ESP32C6_DOCS, - "esp32h2": ESP32H2_DOCS, -} +# ESP32_DOCS = [ +# "index.rst", +# ] + +# ESP32S2_DOCS = ESP32_DOCS +# ESP32C3_DOCS = ESP32S2_DOCS +# ESP32S3_DOCS = ESP32S2_DOCS +# ESP32C6_DOCS = ESP32S2_DOCS +# ESP32H2_DOCS = ESP32S2_DOCS + +# conditional_include_dict = { +# "esp32": ESP32_DOCS, +# "esp32s2": ESP32S2_DOCS, +# "esp32c3": ESP32C3_DOCS, +# "esp32s3": ESP32S3_DOCS, +# "esp32c6": ESP32C6_DOCS, +# "esp32h2": ESP32H2_DOCS, +# } # Extra options required by sphinx_idf_theme project_slug = "arduino-esp32" -versions_url = "./_static/arduino_versions.js" +# versions_url = "./_static/arduino_versions.js" diff --git a/docs/en/index.rst b/docs/en/index.rst index f7f93f9cc92..11a4f8539c5 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -2,7 +2,7 @@ Welcome to Arduino Core's documentation ####################################### -Here you will find all the relevant information about the project based on the {IDF_TARGET_NAME}. +Here you will find all the relevant information about the project based on the Arduino Core ESP32. .. note:: This is a work in progress documentation and we will appreciate your help! We are looking for contributors! From 91da8c6fa10a9e5ac11e466fb32df29eebac9117 Mon Sep 17 00:00:00 2001 From: pedrominatel Date: Fri, 8 Dec 2023 11:31:53 +0800 Subject: [PATCH 14/21] Documentation build and deploy CI changed --- .github/workflows/docs.yml | 46 +++++++++++++++++++++++++-- .github/workflows/docs_deploy.yml | 53 ------------------------------- 2 files changed, 44 insertions(+), 55 deletions(-) delete mode 100644 .github/workflows/docs_deploy.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 2ca6b0a3cad..1152b97278e 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,4 +1,4 @@ -name: Documentation Build CI +name: Documentation Build and Deploy CI on: push: @@ -41,4 +41,46 @@ jobs: uses: actions/upload-artifact@v2 with: name: docs - path: docs \ No newline at end of file + path: docs + + deploy-preview-docs: + name: Deploy Documentation + runs-on: ubuntu-22.04 + defaults: + run: + shell: bash + steps: + - uses: actions/checkout@v2 + with: + submodules: true + - uses: actions/setup-python@v2 + with: + python-version: '3.10' + - name: Deploy Preview + env: + # Deploy to production server + # DOCS_BUILD_DIR: "./docs/_build/" + # DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_DEPLOY_KEY }} + # DOCS_DEPLOY_SERVER: ${{ secrets.DOCS_SERVER }} + # DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_SERVER_USER }} + # DOCS_DEPLOY_PATH: ${{ secrets.DOCS_PATH }} + # DOCS_DEPLOY_URL_BASE: ${{ secrets.DOCS_URL }} + # Deploy to preview server + DOCS_DIR: "./docs/_build/" + DOCS_KEY: ${{ secrets.DOCS_KEY }} + DOCS_PATH: ${{ secrets.DOCS_PATH }} + DOCS_SERVER: ${{ secrets.DOCS_SERVER }} + DOCS_URL: ${{ secrets.DOCS_URL }} + DOCS_USER: ${{ secrets.DOCS_USER }} + run: | + sudo apt update + sudo apt install python3-pip python3-setuptools + source ./docs/utils.sh + add_doc_server_ssh_keys $DOCS_DEPLOY_PRIVATEKEY $DOCS_DEPLOY_SERVER $DOCS_DEPLOY_SERVER_USER + export GIT_VER=$(git describe --always) + echo "PIP install requirements..." + pip3 install --user -r ./docs/requirements.txt + echo "Building the Docs..." + cd ./docs && build-docs -l en + echo "Deploy the Docs..." + deploy-docs diff --git a/.github/workflows/docs_deploy.yml b/.github/workflows/docs_deploy.yml deleted file mode 100644 index 16d7408a4e4..00000000000 --- a/.github/workflows/docs_deploy.yml +++ /dev/null @@ -1,53 +0,0 @@ -name: Documentation Deploy CI - -// Deploy to production on each merge to master -on: - push: - branches: - - master - paths: - - 'docs/**' - - '.github/workflows/docs_deploy.yml' - -jobs: - deploy-preview-docs: - name: Deploy Documentation - runs-on: ubuntu-22.04 - defaults: - run: - shell: bash - steps: - - uses: actions/checkout@v2 - with: - submodules: true - - uses: actions/setup-python@v2 - with: - python-version: '3.10' - - name: Deploy Preview - env: - # Deploy to production server - # DOCS_BUILD_DIR: "./docs/_build/" - # DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_DEPLOY_KEY }} - # DOCS_DEPLOY_SERVER: ${{ secrets.DOCS_SERVER }} - # DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_SERVER_USER }} - # DOCS_DEPLOY_PATH: ${{ secrets.DOCS_PATH }} - # DOCS_DEPLOY_URL_BASE: ${{ secrets.DOCS_URL }} - # Deploy to preview server - DOCS_BUILD_DIR: "./docs/_build/" - DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_PREV_DEPLOY_KEY }} - DOCS_DEPLOY_SERVER: ${{ secrets.DOCS_PREV_SERVER }} - DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_PREV_SERVER_USER }} - DOCS_DEPLOY_PATH: ${{ secrets.DOCS_PREV_PATH }} - DOCS_DEPLOY_URL_BASE: ${{ secrets.DOCS_PREV_URL }} - run: | - sudo apt update - sudo apt install python3-pip python3-setuptools - source ./docs/utils.sh - add_doc_server_ssh_keys $DOCS_DEPLOY_PRIVATEKEY $DOCS_DEPLOY_SERVER $DOCS_DEPLOY_SERVER_USER - export GIT_VER=$(git describe --always) - echo "PIP install requirements..." - pip3 install --user -r ./docs/requirements.txt - echo "Building the Docs..." - cd ./docs && build-docs -l en - echo "Deploy the Docs..." - deploy-docs From f99d7848e8ab8c835a29ddcc29f770763308464c Mon Sep 17 00:00:00 2001 From: pedrominatel Date: Fri, 8 Dec 2023 11:37:00 +0800 Subject: [PATCH 15/21] Fixed env vars from server side --- .github/workflows/docs.yml | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 1152b97278e..6cef7b8fe71 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -66,12 +66,13 @@ jobs: # DOCS_DEPLOY_PATH: ${{ secrets.DOCS_PATH }} # DOCS_DEPLOY_URL_BASE: ${{ secrets.DOCS_URL }} # Deploy to preview server - DOCS_DIR: "./docs/_build/" - DOCS_KEY: ${{ secrets.DOCS_KEY }} - DOCS_PATH: ${{ secrets.DOCS_PATH }} - DOCS_SERVER: ${{ secrets.DOCS_SERVER }} + + DOCS_BUILD_DIR: "./docs/_build/" + DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_KEY }} + DOCS_DEPLOY_PATH: ${{ secrets.DOCS_PATH }} + DOCS_DEPLOY_SERVER: ${{ secrets.DOCS_SERVER }} DOCS_URL: ${{ secrets.DOCS_URL }} - DOCS_USER: ${{ secrets.DOCS_USER }} + DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_USER }} run: | sudo apt update sudo apt install python3-pip python3-setuptools From 9a72b42788f88f5002dc4561b0245f79ab995d1a Mon Sep 17 00:00:00 2001 From: pedrominatel Date: Fri, 8 Dec 2023 11:39:00 +0800 Subject: [PATCH 16/21] Fixed env vars from server side URL base --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 6cef7b8fe71..e4d354c20de 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -71,7 +71,7 @@ jobs: DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_KEY }} DOCS_DEPLOY_PATH: ${{ secrets.DOCS_PATH }} DOCS_DEPLOY_SERVER: ${{ secrets.DOCS_SERVER }} - DOCS_URL: ${{ secrets.DOCS_URL }} + DOCS_DEPLOY_URL_BASE: ${{ secrets.DOCS_URL }} DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_USER }} run: | sudo apt update From b75b6a3e93556782d0f9e27dfc5d876e407e9d09 Mon Sep 17 00:00:00 2001 From: pedrominatel Date: Fri, 8 Dec 2023 11:47:44 +0800 Subject: [PATCH 17/21] Deploy on preview server --- .github/workflows/docs.yml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index e4d354c20de..8e6c2f31da5 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -68,16 +68,16 @@ jobs: # Deploy to preview server DOCS_BUILD_DIR: "./docs/_build/" - DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_KEY }} - DOCS_DEPLOY_PATH: ${{ secrets.DOCS_PATH }} - DOCS_DEPLOY_SERVER: ${{ secrets.DOCS_SERVER }} - DOCS_DEPLOY_URL_BASE: ${{ secrets.DOCS_URL }} - DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_USER }} + DOCS_PREVIEW_PRIVATEKEY: ${{ secrets.DOCS_KEY }} + DOCS_PREVIEW_PATH: ${{ secrets.DOCS_PATH }} + DOCS_PREVIEW_SERVER: ${{ secrets.DOCS_SERVER }} + DOCS_PREVIEW_URL_BASE: ${{ secrets.DOCS_URL }} + DOCS_PREVIEW_USER: ${{ secrets.DOCS_USER }} run: | sudo apt update sudo apt install python3-pip python3-setuptools source ./docs/utils.sh - add_doc_server_ssh_keys $DOCS_DEPLOY_PRIVATEKEY $DOCS_DEPLOY_SERVER $DOCS_DEPLOY_SERVER_USER + add_doc_server_ssh_keys $DOCS_PREVIEW_PRIVATEKEY $DOCS_PREVIEW_SERVER $DOCS_PREVIEW_USER export GIT_VER=$(git describe --always) echo "PIP install requirements..." pip3 install --user -r ./docs/requirements.txt From 637c4e945f12e1c9a49e9f5824aeea9e4e2c1d20 Mon Sep 17 00:00:00 2001 From: pedrominatel Date: Fri, 8 Dec 2023 11:56:09 +0800 Subject: [PATCH 18/21] Deploy on preview server add type var --- .github/workflows/docs.yml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 8e6c2f31da5..ec4fff94995 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -66,18 +66,18 @@ jobs: # DOCS_DEPLOY_PATH: ${{ secrets.DOCS_PATH }} # DOCS_DEPLOY_URL_BASE: ${{ secrets.DOCS_URL }} # Deploy to preview server - - DOCS_BUILD_DIR: "./docs/_build/" - DOCS_PREVIEW_PRIVATEKEY: ${{ secrets.DOCS_KEY }} - DOCS_PREVIEW_PATH: ${{ secrets.DOCS_PATH }} - DOCS_PREVIEW_SERVER: ${{ secrets.DOCS_SERVER }} - DOCS_PREVIEW_URL_BASE: ${{ secrets.DOCS_URL }} - DOCS_PREVIEW_USER: ${{ secrets.DOCS_USER }} + TYPE: "preview" + DOCS_BUILD_DIR: "${CI_PROJECT_DIR}/docs/_build/" + DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_KEY }} + DOCS_DEPLOY_PATH: ${{ secrets.DOCS_PATH }} + DOCS_DEPLOY_SERVER: ${{ secrets.DOCS_SERVER }} + DOCS_DEPLOY_URL_BASE: ${{ secrets.DOCS_URL }} + DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_USER }} run: | sudo apt update sudo apt install python3-pip python3-setuptools source ./docs/utils.sh - add_doc_server_ssh_keys $DOCS_PREVIEW_PRIVATEKEY $DOCS_PREVIEW_SERVER $DOCS_PREVIEW_USER + add_doc_server_ssh_keys $DOCS_DEPLOY_PRIVATEKEY $DOCS_DEPLOY_SERVER $DOCS_DEPLOY_SERVER_USER export GIT_VER=$(git describe --always) echo "PIP install requirements..." pip3 install --user -r ./docs/requirements.txt From 28916413d56a8f3b67ff57bd5e5439688d5d26b3 Mon Sep 17 00:00:00 2001 From: pedrominatel Date: Fri, 8 Dec 2023 12:28:51 +0800 Subject: [PATCH 19/21] Deploy on preview server - Change the URL --- .github/workflows/docs.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ec4fff94995..2318efc06fa 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -70,8 +70,10 @@ jobs: DOCS_BUILD_DIR: "${CI_PROJECT_DIR}/docs/_build/" DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_KEY }} DOCS_DEPLOY_PATH: ${{ secrets.DOCS_PATH }} - DOCS_DEPLOY_SERVER: ${{ secrets.DOCS_SERVER }} + # DOCS_DEPLOY_SERVER: ${{ secrets.DOCS_SERVER }} + DOCS_DEPLOY_SERVER: "preview-docs.espressif.com" DOCS_DEPLOY_URL_BASE: ${{ secrets.DOCS_URL }} + # DOCS_DEPLOY_URL_BASE: "https://docs.espressif.com/projects/arduino-esp32" DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_USER }} run: | sudo apt update From b997f4cabab7f78add85c79be17d954018bcd0bb Mon Sep 17 00:00:00 2001 From: pedrominatel Date: Mon, 11 Dec 2023 11:48:03 +0800 Subject: [PATCH 20/21] Deploy on preview server CI changes --- .github/workflows/docs.yml | 4 +- .github/workflows/docs_deploy.yml | 87 +++++++++++++++++++++++++++++++ .github/workflows/docs_legacy.yml | 38 ++++++++++++++ 3 files changed, 126 insertions(+), 3 deletions(-) create mode 100644 .github/workflows/docs_deploy.yml create mode 100644 .github/workflows/docs_legacy.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 2318efc06fa..ec4fff94995 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -70,10 +70,8 @@ jobs: DOCS_BUILD_DIR: "${CI_PROJECT_DIR}/docs/_build/" DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_KEY }} DOCS_DEPLOY_PATH: ${{ secrets.DOCS_PATH }} - # DOCS_DEPLOY_SERVER: ${{ secrets.DOCS_SERVER }} - DOCS_DEPLOY_SERVER: "preview-docs.espressif.com" + DOCS_DEPLOY_SERVER: ${{ secrets.DOCS_SERVER }} DOCS_DEPLOY_URL_BASE: ${{ secrets.DOCS_URL }} - # DOCS_DEPLOY_URL_BASE: "https://docs.espressif.com/projects/arduino-esp32" DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_USER }} run: | sudo apt update diff --git a/.github/workflows/docs_deploy.yml b/.github/workflows/docs_deploy.yml new file mode 100644 index 00000000000..ec4fff94995 --- /dev/null +++ b/.github/workflows/docs_deploy.yml @@ -0,0 +1,87 @@ +name: Documentation Build and Deploy CI + +on: + push: + branches: + - master + - release/* + paths: + - 'docs/**' + - '.github/workflows/docs.yml' + pull_request: + paths: + - 'docs/**' + - '.github/workflows/docs.yml' + +jobs: + + build-docs: + name: Build ESP-Docs + runs-on: ubuntu-22.04 + defaults: + run: + shell: bash + steps: + - uses: actions/checkout@v3 + with: + submodules: true + - uses: actions/setup-python@v4 + with: + python-version: '3.10' + - name: Build + run: | + sudo apt update + sudo apt install python3-pip python3-setuptools + # GitHub CI installs pip3 and setuptools outside the path. + # Update the path to include them and run. + cd ./docs + PATH=/home/runner/.local/bin:$PATH pip3 install -r requirements.txt --prefer-binary + PATH=/home/runner/.local/bin:$PATH SPHINXOPTS="-W" build-docs -l en + - name: Archive Docs + uses: actions/upload-artifact@v2 + with: + name: docs + path: docs + + deploy-preview-docs: + name: Deploy Documentation + runs-on: ubuntu-22.04 + defaults: + run: + shell: bash + steps: + - uses: actions/checkout@v2 + with: + submodules: true + - uses: actions/setup-python@v2 + with: + python-version: '3.10' + - name: Deploy Preview + env: + # Deploy to production server + # DOCS_BUILD_DIR: "./docs/_build/" + # DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_DEPLOY_KEY }} + # DOCS_DEPLOY_SERVER: ${{ secrets.DOCS_SERVER }} + # DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_SERVER_USER }} + # DOCS_DEPLOY_PATH: ${{ secrets.DOCS_PATH }} + # DOCS_DEPLOY_URL_BASE: ${{ secrets.DOCS_URL }} + # Deploy to preview server + TYPE: "preview" + DOCS_BUILD_DIR: "${CI_PROJECT_DIR}/docs/_build/" + DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_KEY }} + DOCS_DEPLOY_PATH: ${{ secrets.DOCS_PATH }} + DOCS_DEPLOY_SERVER: ${{ secrets.DOCS_SERVER }} + DOCS_DEPLOY_URL_BASE: ${{ secrets.DOCS_URL }} + DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_USER }} + run: | + sudo apt update + sudo apt install python3-pip python3-setuptools + source ./docs/utils.sh + add_doc_server_ssh_keys $DOCS_DEPLOY_PRIVATEKEY $DOCS_DEPLOY_SERVER $DOCS_DEPLOY_SERVER_USER + export GIT_VER=$(git describe --always) + echo "PIP install requirements..." + pip3 install --user -r ./docs/requirements.txt + echo "Building the Docs..." + cd ./docs && build-docs -l en + echo "Deploy the Docs..." + deploy-docs diff --git a/.github/workflows/docs_legacy.yml b/.github/workflows/docs_legacy.yml new file mode 100644 index 00000000000..d725f8a1d1b --- /dev/null +++ b/.github/workflows/docs_legacy.yml @@ -0,0 +1,38 @@ +name: Build the Docs Legacy ReadTheDocs CI + +on: + push: + branches: + - master + - release/* + paths: + - 'docs/**' + - '.github/workflows/docs_legacy.yml' + pull_request: + paths: + - 'docs/**' + - '.github/workflows/docs_legacy.yml' + +jobs: + + build-docs: + name: Build ReadTheDocs + runs-on: ubuntu-22.04 + defaults: + run: + shell: bash + steps: + - uses: actions/checkout@v3 + with: + submodules: true + - uses: actions/setup-python@v4 + with: + python-version: '3.10' + - name: Build + run: | + sudo apt update + sudo apt install python3-pip python3-setuptools + # GitHub CI installs pip3 and setuptools outside the path. + # Update the path to include them and run. + PATH=/home/runner/.local/bin:$PATH pip3 install --user -r ./docs/requirements.txt + cd ./docs && PATH=/home/runner/.local/bin:$PATH SPHINXOPTS="-W" make html From 21c710cbfc98a2fe1ec1af20d29d522a29a1ea47 Mon Sep 17 00:00:00 2001 From: pedrominatel Date: Fri, 12 Jan 2024 11:26:27 +0000 Subject: [PATCH 21/21] Docs deploy CI updated for production deployment --- .github/workflows/docs.yml | 87 ------------------- .../{docs_legacy.yml => docs_build.yml} | 23 +++-- .github/workflows/docs_deploy.yml | 57 ++---------- .github/workflows/docs_preview.yml | 46 ++++++++++ docs/utils.sh | 2 +- 5 files changed, 66 insertions(+), 149 deletions(-) delete mode 100644 .github/workflows/docs.yml rename .github/workflows/{docs_legacy.yml => docs_build.yml} (56%) create mode 100644 .github/workflows/docs_preview.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml deleted file mode 100644 index ec4fff94995..00000000000 --- a/.github/workflows/docs.yml +++ /dev/null @@ -1,87 +0,0 @@ -name: Documentation Build and Deploy CI - -on: - push: - branches: - - master - - release/* - paths: - - 'docs/**' - - '.github/workflows/docs.yml' - pull_request: - paths: - - 'docs/**' - - '.github/workflows/docs.yml' - -jobs: - - build-docs: - name: Build ESP-Docs - runs-on: ubuntu-22.04 - defaults: - run: - shell: bash - steps: - - uses: actions/checkout@v3 - with: - submodules: true - - uses: actions/setup-python@v4 - with: - python-version: '3.10' - - name: Build - run: | - sudo apt update - sudo apt install python3-pip python3-setuptools - # GitHub CI installs pip3 and setuptools outside the path. - # Update the path to include them and run. - cd ./docs - PATH=/home/runner/.local/bin:$PATH pip3 install -r requirements.txt --prefer-binary - PATH=/home/runner/.local/bin:$PATH SPHINXOPTS="-W" build-docs -l en - - name: Archive Docs - uses: actions/upload-artifact@v2 - with: - name: docs - path: docs - - deploy-preview-docs: - name: Deploy Documentation - runs-on: ubuntu-22.04 - defaults: - run: - shell: bash - steps: - - uses: actions/checkout@v2 - with: - submodules: true - - uses: actions/setup-python@v2 - with: - python-version: '3.10' - - name: Deploy Preview - env: - # Deploy to production server - # DOCS_BUILD_DIR: "./docs/_build/" - # DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_DEPLOY_KEY }} - # DOCS_DEPLOY_SERVER: ${{ secrets.DOCS_SERVER }} - # DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_SERVER_USER }} - # DOCS_DEPLOY_PATH: ${{ secrets.DOCS_PATH }} - # DOCS_DEPLOY_URL_BASE: ${{ secrets.DOCS_URL }} - # Deploy to preview server - TYPE: "preview" - DOCS_BUILD_DIR: "${CI_PROJECT_DIR}/docs/_build/" - DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_KEY }} - DOCS_DEPLOY_PATH: ${{ secrets.DOCS_PATH }} - DOCS_DEPLOY_SERVER: ${{ secrets.DOCS_SERVER }} - DOCS_DEPLOY_URL_BASE: ${{ secrets.DOCS_URL }} - DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_USER }} - run: | - sudo apt update - sudo apt install python3-pip python3-setuptools - source ./docs/utils.sh - add_doc_server_ssh_keys $DOCS_DEPLOY_PRIVATEKEY $DOCS_DEPLOY_SERVER $DOCS_DEPLOY_SERVER_USER - export GIT_VER=$(git describe --always) - echo "PIP install requirements..." - pip3 install --user -r ./docs/requirements.txt - echo "Building the Docs..." - cd ./docs && build-docs -l en - echo "Deploy the Docs..." - deploy-docs diff --git a/.github/workflows/docs_legacy.yml b/.github/workflows/docs_build.yml similarity index 56% rename from .github/workflows/docs_legacy.yml rename to .github/workflows/docs_build.yml index d725f8a1d1b..c18120c079f 100644 --- a/.github/workflows/docs_legacy.yml +++ b/.github/workflows/docs_build.yml @@ -1,22 +1,15 @@ -name: Build the Docs Legacy ReadTheDocs CI +name: Documentation Build and Deploy CI on: - push: - branches: - - master - - release/* - paths: - - 'docs/**' - - '.github/workflows/docs_legacy.yml' pull_request: paths: - 'docs/**' - - '.github/workflows/docs_legacy.yml' + - '.github/workflows/docs.yml' jobs: build-docs: - name: Build ReadTheDocs + name: Build Documentation runs-on: ubuntu-22.04 defaults: run: @@ -34,5 +27,11 @@ jobs: sudo apt install python3-pip python3-setuptools # GitHub CI installs pip3 and setuptools outside the path. # Update the path to include them and run. - PATH=/home/runner/.local/bin:$PATH pip3 install --user -r ./docs/requirements.txt - cd ./docs && PATH=/home/runner/.local/bin:$PATH SPHINXOPTS="-W" make html + cd ./docs + PATH=/home/runner/.local/bin:$PATH pip3 install -r requirements.txt --prefer-binary + PATH=/home/runner/.local/bin:$PATH SPHINXOPTS="-W" build-docs -l en + - name: Archive Docs + uses: actions/upload-artifact@v2 + with: + name: docs + path: docs diff --git a/.github/workflows/docs_deploy.yml b/.github/workflows/docs_deploy.yml index ec4fff94995..ebc8acac792 100644 --- a/.github/workflows/docs_deploy.yml +++ b/.github/workflows/docs_deploy.yml @@ -1,50 +1,17 @@ -name: Documentation Build and Deploy CI +name: Documentation Build and Deploy Production CI on: push: branches: - - master - release/* paths: - 'docs/**' - '.github/workflows/docs.yml' - pull_request: - paths: - - 'docs/**' - - '.github/workflows/docs.yml' jobs: - build-docs: - name: Build ESP-Docs - runs-on: ubuntu-22.04 - defaults: - run: - shell: bash - steps: - - uses: actions/checkout@v3 - with: - submodules: true - - uses: actions/setup-python@v4 - with: - python-version: '3.10' - - name: Build - run: | - sudo apt update - sudo apt install python3-pip python3-setuptools - # GitHub CI installs pip3 and setuptools outside the path. - # Update the path to include them and run. - cd ./docs - PATH=/home/runner/.local/bin:$PATH pip3 install -r requirements.txt --prefer-binary - PATH=/home/runner/.local/bin:$PATH SPHINXOPTS="-W" build-docs -l en - - name: Archive Docs - uses: actions/upload-artifact@v2 - with: - name: docs - path: docs - - deploy-preview-docs: - name: Deploy Documentation + deploy-prod-docs: + name: Deploy Documentation Production runs-on: ubuntu-22.04 defaults: run: @@ -59,20 +26,12 @@ jobs: - name: Deploy Preview env: # Deploy to production server - # DOCS_BUILD_DIR: "./docs/_build/" - # DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_DEPLOY_KEY }} - # DOCS_DEPLOY_SERVER: ${{ secrets.DOCS_SERVER }} - # DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_SERVER_USER }} - # DOCS_DEPLOY_PATH: ${{ secrets.DOCS_PATH }} - # DOCS_DEPLOY_URL_BASE: ${{ secrets.DOCS_URL }} - # Deploy to preview server - TYPE: "preview" DOCS_BUILD_DIR: "${CI_PROJECT_DIR}/docs/_build/" - DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_KEY }} - DOCS_DEPLOY_PATH: ${{ secrets.DOCS_PATH }} - DOCS_DEPLOY_SERVER: ${{ secrets.DOCS_SERVER }} - DOCS_DEPLOY_URL_BASE: ${{ secrets.DOCS_URL }} - DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_USER }} + DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_PROD_PRIVATEKEY }} + DOCS_DEPLOY_PATH: ${{ secrets.DOCS_PROD_PATH }} + DOCS_DEPLOY_SERVER: ${{ secrets.DOCS_PROD_SERVER }} + DOCS_DEPLOY_URL_BASE: ${{ secrets.DOCS_PROD_URL_BASE }} + DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_PROD_USER }} run: | sudo apt update sudo apt install python3-pip python3-setuptools diff --git a/.github/workflows/docs_preview.yml b/.github/workflows/docs_preview.yml new file mode 100644 index 00000000000..41de91838b3 --- /dev/null +++ b/.github/workflows/docs_preview.yml @@ -0,0 +1,46 @@ +name: Documentation Build and Deploy CI + +on: + push: + branches: + - master + paths: + - 'docs/**' + - '.github/workflows/docs.yml' + +jobs: + + deploy-preview-docs: + name: Deploy Documentation Preview + runs-on: ubuntu-22.04 + defaults: + run: + shell: bash + steps: + - uses: actions/checkout@v3 + with: + submodules: true + - uses: actions/setup-python@v4 + with: + python-version: '3.10' + - name: Deploy Preview + env: + # Deploy to preview server + DOCS_BUILD_DIR: "${CI_PROJECT_DIR}/docs/_build/" + DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_KEY }} + DOCS_DEPLOY_PATH: ${{ secrets.DOCS_PATH }} + DOCS_DEPLOY_SERVER: ${{ secrets.DOCS_SERVER }} + DOCS_DEPLOY_URL_BASE: ${{ secrets.DOCS_URL }} + DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_USER }} + run: | + sudo apt update + sudo apt install python3-pip python3-setuptools + source ./docs/utils.sh + add_doc_server_ssh_keys $DOCS_DEPLOY_PRIVATEKEY $DOCS_DEPLOY_SERVER $DOCS_DEPLOY_SERVER_USER + export GIT_VER=$(git describe --always) + echo "PIP install requirements..." + pip3 install --user -r ./docs/requirements.txt + echo "Building the Docs..." + cd ./docs && build-docs -l en + echo "Deploy the Docs..." + deploy-docs diff --git a/docs/utils.sh b/docs/utils.sh index 91e283d462f..0f9574e57a5 100644 --- a/docs/utils.sh +++ b/docs/utils.sh @@ -5,7 +5,7 @@ function add_ssh_keys() { mkdir -p ~/.ssh chmod 700 ~/.ssh echo -n "${key_string}" >~/.ssh/id_rsa_base64 - base64 -w 0 ~/.ssh/id_rsa_base64 | base64 -di >~/.ssh/id_rsa + base64 --decode --ignore-garbage ~/.ssh/id_rsa_base64 >~/.ssh/id_rsa chmod 600 ~/.ssh/id_rsa }