From e4d6a8abf9fab7422e21f72d3aeb2e9c9484ab36 Mon Sep 17 00:00:00 2001 From: Pedro Minatel Date: Fri, 12 Jan 2024 17:44:42 +0000 Subject: [PATCH] Documentation migration from RTD to ESP-Docs (#9094) --- .../workflows/{docs.yml => docs_build.yml} | 21 +++-- .github/workflows/docs_deploy.yml | 46 +++++++++++ .github/workflows/docs_preview.yml | 46 +++++++++++ docs/Makefile | 28 ------- docs/{source => }/_static/arduino-ide.png | Bin .../_static/arduino_i2c_master.png | Bin .../_static/arduino_i2c_slave.png | Bin docs/_static/arduino_versions.js | 16 ++++ 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 | 54 +++++++++++++ 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/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 | 31 ++++++++ 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 | 4 +- 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 .../migration_guides/2.x_to_3.0.rst | 0 .../migration_guides/migration_guides.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 | 6 +- docs/source/conf.py | 72 ------------------ docs/utils.sh | 18 +++++ 109 files changed, 265 insertions(+), 194 deletions(-) rename .github/workflows/{docs.yml => docs_build.yml} (60%) create mode 100644 .github/workflows/docs_deploy.yml create mode 100644 .github/workflows/docs_preview.yml delete mode 100644 docs/Makefile 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%) create mode 100644 docs/_static/arduino_versions.js 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/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 (98%) 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 (95%) 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}/migration_guides/2.x_to_3.0.rst (100%) rename docs/{source => en}/migration_guides/migration_guides.rst (100%) rename docs/{source => en}/ota_web_update.rst (94%) 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 create mode 100644 docs/utils.sh diff --git a/.github/workflows/docs.yml b/.github/workflows/docs_build.yml similarity index 60% rename from .github/workflows/docs.yml rename to .github/workflows/docs_build.yml index f01fb76ee84..c18120c079f 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs_build.yml @@ -1,13 +1,6 @@ -name: ReadTheDocs CI +name: Documentation Build and Deploy CI on: - push: - branches: - - master - - release/* - paths: - - 'docs/**' - - '.github/workflows/docs.yml' pull_request: paths: - 'docs/**' @@ -16,7 +9,7 @@ on: 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 new file mode 100644 index 00000000000..ebc8acac792 --- /dev/null +++ b/.github/workflows/docs_deploy.yml @@ -0,0 +1,46 @@ +name: Documentation Build and Deploy Production CI + +on: + push: + branches: + - release/* + paths: + - 'docs/**' + - '.github/workflows/docs.yml' + +jobs: + + deploy-prod-docs: + name: Deploy Documentation Production + 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: "${CI_PROJECT_DIR}/docs/_build/" + 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 + 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_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/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/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/_static/arduino_versions.js b/docs/_static/arduino_versions.js new file mode 100644 index 00000000000..825bc0cbc27 --- /dev/null +++ b/docs/_static/arduino_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: "ESP32-C6", value: "esp32c6"}, + ] +}; 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..dd37c809849 --- /dev/null +++ b/docs/conf_common.py @@ -0,0 +1,54 @@ +# --------------------------------------------------------------- + +from esp_docs.conf_docs import * # noqa: F403,F401 + +languages = ["en"] + +# idf_targets = [ +# "esp32", +# "esp32s2", +# "esp32s3", +# "esp32c3", +# "esp32c6", +# "esp32h2", +# ] + +# 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", +# ] + +# 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" 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/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 c906cdaa588..d7bb60cce7c 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 6214fe4ebd1..7115d5bcb4e 100644 --- a/docs/source/boards/boards.rst +++ b/docs/en/boards/boards.rst @@ -30,7 +30,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) @@ -60,7 +60,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..9979662dae0 --- /dev/null +++ b/docs/en/conf.py @@ -0,0 +1,31 @@ +# -*- 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 + +import datetime +current_year = datetime.datetime.now().year + +# General information about the project. +project = u'Arduino ESP32' +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 +# for a list of supported languages. +language = 'en' + +# Tracking ID for Google Analytics +google_analytics_id = 'G-F58JM78930' \ 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 3540dda685b..9267f1b427f 100644 --- a/docs/source/getting_started.rst +++ b/docs/en/getting_started.rst @@ -64,9 +64,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 --------------------------- @@ -79,8 +79,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 98% rename from docs/source/guides/docs_contributing.rst rename to docs/en/guides/docs_contributing.rst index be5a54e4b37..d0089a5fd9f 100644 --- a/docs/source/guides/docs_contributing.rst +++ b/docs/en/guides/docs_contributing.rst @@ -97,7 +97,7 @@ If everything is ok, you will see some output logs similar to this one: writing output... [100%] tutorials/tutorials generating indices... genindexdone writing additional pages... searchdone - copying images... [100%] tutorials/../_static/tutorials/peripherals/tutorial_peripheral_diagram.png + copying images... [100%] tutorials/../../_static/tutorials/peripherals/tutorial_peripheral_diagram.png copying static files... ... done copying extra files... done dumping search index in English (code: en)... done @@ -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 95% rename from docs/source/installing.rst rename to docs/en/installing.rst index 3b5554baf32..3acabd5505c 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 @@ -166,7 +166,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 @@ -179,13 +179,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 @@ -194,7 +194,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 @@ -202,7 +202,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 @@ -212,7 +212,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 @@ -221,27 +221,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/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/source/ota_web_update.rst b/docs/en/ota_web_update.rst similarity index 94% rename from docs/source/ota_web_update.rst rename to docs/en/ota_web_update.rst index be0a6d5e263..179101770a0 100644 --- a/docs/source/ota_web_update.rst +++ b/docs/en/ota_web_update.rst @@ -39,14 +39,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 @@ -59,7 +59,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 @@ -70,7 +70,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 da0d937707a..97b552574b9 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,7 +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-rtd-theme +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 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/utils.sh b/docs/utils.sh new file mode 100644 index 00000000000..0f9574e57a5 --- /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 --decode --ignore-garbage ~/.ssh/id_rsa_base64 >~/.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