Documentation migration from RTD to ESP-Docs (#9094)

.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

.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

.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

docs/Makefile

@@ -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)

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"},
+    ]
+};

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"

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

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

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)

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)

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)

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

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'

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
 

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 <installing.html>`_ for more details on how to install the Arduino ESP32 support.
 

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

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

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

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
 

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)