[Docs] New docs theme based on ESP-IDF style (#6512)

Author: pedrominatel

.github/workflows/docs.yml

@@ -1,4 +1,4 @@
-name: ReadTheDocs CI
+name: Docs CI
 
 on:
   push:
@@ -15,8 +15,8 @@ on:
 
 jobs:
 
-  build-docs:
-    name: Build ReadTheDocs
+  deploy-preview-docs:
+    name: Deploy Preview Docs
     runs-on: ubuntu-latest
     defaults:
       run:
@@ -28,11 +28,23 @@ jobs:
     - uses: actions/setup-python@v2
       with:
         python-version: '3.x'
-    - name: Build
+    - 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
-        # 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
+        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

.gitignore

@@ -23,6 +23,8 @@ boards.sloeber.txt
 # Ignore docs build (Sphinx)
 docs/build
 docs/source/_build
+docs/__pycache__/
+docs/_build/
 
 # Test log files
 *.log

docs/Makefile

@@ -0,0 +1,26 @@
+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"

docs/source/_static/arduino-ide.png renamed to docs/_static/arduino-ide.png

@@ -0,0 +1,29 @@
+# -*- 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
+
+import datetime
+
+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 = "Arduino-ESP32"
+copyright = "2016 - {}, Espressif Systems (Shanghai) Co., Ltd".format(
+    datetime.datetime.now().year
+)
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+language = "en"