diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 8716ab3..190306c 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -7,6 +7,8 @@ variables:
MAKEFLAGS: "-j8 --no-keep-going"
APP_BUILD: "all"
GIT_SUBMODULE_STRATEGY: recursive
+ ESP_DOCS_ENV_IMAGE: "$CI_DOCKER_REGISTRY/esp-idf-doc-env-v5.0:2-2"
+ ESP_DOCS_PATH: "$CI_PROJECT_DIR"
before_script:
# add gitlab ssh key
@@ -170,31 +172,68 @@ build_matter:
- *build_matter_controller_example
build_docs:
- stage: build
- image: $CI_DOCKER_REGISTRY/esp32-ci-env
- tags:
- - build
- artifacts:
- paths:
- - $CI_PROJECT_DIR/esp-rainmaker-docs-${CI_JOB_ID}.zip
- script:
- # Building sphinx docs
- - echo Building sphinx docs
- - cd docs
- # unset IDF_PATH
- - echo Unset IDF_PATH
- - unset IDF_PATH
- # Run requirements.txt
- - echo Run requirements.txt
- - python3 -m pip install -r requirements.txt
- # Run make html
- - echo Run make html
- - make html
- - cd $CI_PROJECT_DIR
- - echo Generating tar files
- - mkdir -p esp-rainmaker-docs-${CI_JOB_ID}/html
- - cp -rf $CI_PROJECT_DIR/docs/_build/html/ esp-rainmaker-docs-${CI_JOB_ID}/html/
- - tar -zcvf esp-rainmaker-docs-${CI_JOB_ID}.zip esp-rainmaker-docs-${CI_JOB_ID}
+ stage: build
+ image: $ESP_DOCS_ENV_IMAGE
+ tags:
+ - build_docs
+ artifacts:
+ paths:
+ - docs/_build/*/*/*.txt
+ - docs/_build/*/*/html/*
+ expire_in: 4 days
+ # No cleaning when the artifacts
+ after_script: []
+ script:
+ - cd docs
+ - pip install -r requirements.txt
+ - build-docs -l en -t esp32
+
+.deploy_docs_template:
+ stage: deploy
+ image: $ESP_DOCS_ENV_IMAGE
+ tags:
+ - deploy_docs
+ needs:
+ - build_docs
+ only:
+ changes:
+ - "docs/**/*"
+ script:
+ - source ${CI_PROJECT_DIR}/docs/utils.sh
+ - add_doc_server_ssh_keys $DOCS_DEPLOY_PRIVATEKEY $DOCS_DEPLOY_SERVER $DOCS_DEPLOY_SERVER_USER
+ - export GIT_VER=$(git describe --always)
+ - pip install -r ${CI_PROJECT_DIR}/docs/requirements.txt
+ - deploy-docs
+
+deploy_docs_preview:
+ extends:
+ - .deploy_docs_template
+ except:
+ refs:
+ - master
+ variables:
+ TYPE: "preview"
+ DOCS_BUILD_DIR: "${CI_PROJECT_DIR}/docs/_build/"
+ DOCS_DEPLOY_PRIVATEKEY: "$DOCS_PREVIEW_PRIVATEKEY"
+ DOCS_DEPLOY_SERVER: "$DOCS_PREVIEW_SERVER"
+ DOCS_DEPLOY_SERVER_USER: "$DOCS_PREVIEW_USER"
+ DOCS_DEPLOY_PATH: "$DOCS_PREVIEW_PATH"
+ DOCS_DEPLOY_URL_BASE: "$DOCS_PREVIEW_URL_BASE"
+
+deploy_docs_production:
+ extends:
+ - .deploy_docs_template
+ only:
+ refs:
+ - master
+ variables:
+ TYPE: "production"
+ DOCS_BUILD_DIR: "${CI_PROJECT_DIR}/docs/_build/"
+ DOCS_DEPLOY_PRIVATEKEY: "$DOCS_PROD_PRIVATEKEY"
+ DOCS_DEPLOY_SERVER: "$DOCS_PROD_SERVER"
+ DOCS_DEPLOY_SERVER_USER: "$DOCS_PROD_USER"
+ DOCS_DEPLOY_PATH: "$DOCS_PROD_PATH"
+ DOCS_DEPLOY_URL_BASE: "$DOCS_PROD_URL_BASE"
push_master_to_github:
stage: deploy
diff --git a/README.md b/README.md
index 0e3b583..e5402f9 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
## Introduction
-ESP RainMaker is an end-to-end solution offered by Espressif to enable remote control and monitoring for ESP32 series of SoCs (e.g., ESP32, ESP32-S2, ESP32-C3, ESP32-C6, ESP32-C2, etc.) based products without any configuration required in the Cloud.
+ESP RainMaker is an end-to-end solution offered by Espressif to enable remote control and monitoring for products based on ESP32 series of SoCs (e.g., ESP32, ESP32-S2, ESP32-C3, ESP32-C6, ESP32-C2, etc.) without any configuration required in the Cloud.
The primary components of this solution are:
diff --git a/docs/Doxyfile b/docs/Doxyfile
index 688b010..3a7ae81 100644
--- a/docs/Doxyfile
+++ b/docs/Doxyfile
@@ -21,29 +21,23 @@ PROJECT_NAME = "ESP RainMaker Programming Guide"
## and used to include in API reference documentation
INPUT = \
- ## RainMaker Core
- ../components/esp_rainmaker/include/esp_rmaker_core.h \
- ../components/esp_rainmaker/include/esp_rmaker_user_mapping.h \
- ../components/esp_rainmaker/include/esp_rmaker_schedule.h \
- ../components/esp_rainmaker/include/esp_rmaker_scenes.h \
- ## RainMaker Standard Types
- ../components/esp_rainmaker/include/esp_rmaker_standard_types.h \
- ../components/esp_rainmaker/include/esp_rmaker_standard_params.h \
- ../components/esp_rainmaker/include/esp_rmaker_standard_devices.h \
- ../components/esp_rainmaker/include/esp_rmaker_standard_services.h \
- ## RainMaker OTA
- ../components/esp_rainmaker/include/esp_rmaker_ota.h \
- ## RainMaker MQTT
- ../components/esp_rainmaker/include/esp_rmaker_mqtt.h \
- ## RainMaker Console
- ../components/esp_rainmaker/include/esp_rmaker_console.h \
- ## RainMaker Common
- ../components/rmaker_common/include/esp_rmaker_common_events.h \
- ../components/rmaker_common/include/esp_rmaker_factory.h \
- ../components/rmaker_common/include/esp_rmaker_work_queue.h \
- ../components/rmaker_common/include/esp_rmaker_utils.h \
- ../components/rmaker_common/include/esp_rmaker_cmd_resp.h \
- ../components/rmaker_common/include/esp_rmaker_mqtt_glue.h
+ $(PROJECT_PATH)/components/esp_rainmaker/include/esp_rmaker_core.h \
+ $(PROJECT_PATH)/components/esp_rainmaker/include/esp_rmaker_user_mapping.h \
+ $(PROJECT_PATH)/components/esp_rainmaker/include/esp_rmaker_schedule.h \
+ $(PROJECT_PATH)/components/esp_rainmaker/include/esp_rmaker_scenes.h \
+ $(PROJECT_PATH)/components/esp_rainmaker/include/esp_rmaker_standard_types.h \
+ $(PROJECT_PATH)/components/esp_rainmaker/include/esp_rmaker_standard_params.h \
+ $(PROJECT_PATH)/components/esp_rainmaker/include/esp_rmaker_standard_devices.h \
+ $(PROJECT_PATH)/components/esp_rainmaker/include/esp_rmaker_standard_services.h \
+ $(PROJECT_PATH)/components/esp_rainmaker/include/esp_rmaker_ota.h \
+ $(PROJECT_PATH)/components/esp_rainmaker/include/esp_rmaker_mqtt.h \
+ $(PROJECT_PATH)/components/esp_rainmaker/include/esp_rmaker_console.h \
+ $(PROJECT_PATH)/components/rmaker_common/include/esp_rmaker_common_events.h \
+ $(PROJECT_PATH)/components/rmaker_common/include/esp_rmaker_factory.h \
+ $(PROJECT_PATH)/components/rmaker_common/include/esp_rmaker_work_queue.h \
+ $(PROJECT_PATH)/components/rmaker_common/include/esp_rmaker_utils.h \
+ $(PROJECT_PATH)/components/rmaker_common/include/esp_rmaker_cmd_resp.h \
+ $(PROJECT_PATH)/components/rmaker_common/include/esp_rmaker_mqtt_glue.h
## Get warnings for functions that have no documentation for their parameters or return value
##
@@ -54,7 +48,11 @@ WARN_NO_PARAMDOC = YES
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
-PREDEFINED =
+PREDEFINED = \
+ $(ENV_DOXYGEN_DEFINES)
+
+## Extract all
+EXTRACT_ALL = YES
## Do not complain about not having dot
##
@@ -77,4 +75,3 @@ QUIET = YES
## Log warnings in a file for further review
##
WARN_LOGFILE = "doxygen-warning-log.txt"
-
diff --git a/docs/README.md b/docs/README.md
index 1d4771c..260e60c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,28 +2,14 @@
This folder contains source files of **ESP RainMaker API documentation**.
-The sources do not render well in GitHub and some information is not visible at all.
-
-Use actual documentation generated within about 20 minutes on each commit:
-
# Hosted Documentation
-* Check here: https://docs.espressif.com/projects/esp-rainmaker/en/latest/
+* Check the following link for the documentation: https://docs.espressif.com/projects/esp-rainmaker/en/latest/
The above URL is for the master branch latest version.
# Building Documentation
-* Install `make` and `doxygen` for your platform (`make` may already be installed as an ESP-IDF prerequisite).
-* Change to the docs directory and run `make html`
-* `make` will probably prompt you to run a python pip install step to get some other Python-related prerequisites. Run the command as shown, then re-run `make html` to build the docs.
-
-## For MSYS2 MINGW32 on Windows
-
-If using Windows and the MSYS2 MINGW32 terminal, run this command before running "make html" the first time:
-
-```
-pacman -S doxygen mingw-w64-i686-python2-pillow
-```
-
-Note: Currently it is not possible to build docs on Windows without using a Unix-on-Windows layer such as MSYS2 MINGW32.
+* ESP RainMaker uses esp-docs for building the docs.
+* Change to the docs directory and run `build-docs -l en -t esp32`
+* To understand more about ESP-Docs, please follow https://docs.espressif.com/projects/esp-docs.
diff --git a/docs/c-api-reference/rainmaker_common.rst b/docs/c-api-reference/rainmaker_common.rst
deleted file mode 100644
index e720d85..0000000
--- a/docs/c-api-reference/rainmaker_common.rst
+++ /dev/null
@@ -1,18 +0,0 @@
-RainMaker Common
-################
-
-Utilities
----------
-.. include:: /_build/inc/esp_rmaker_utils.inc
-
-Factory Storage
----------------
-.. include:: /_build/inc/esp_rmaker_factory.inc
-
-Work Queue
-----------
-.. include:: /_build/inc/esp_rmaker_work_queue.inc
-
-Common Events
--------------
-.. include:: /_build/inc/esp_rmaker_common_events.inc
diff --git a/docs/c-api-reference/rainmaker_console.rst b/docs/c-api-reference/rainmaker_console.rst
deleted file mode 100644
index b0bd225..0000000
--- a/docs/c-api-reference/rainmaker_console.rst
+++ /dev/null
@@ -1,3 +0,0 @@
-RainMaker Console
-#################
-.. include:: /_build/inc/esp_rmaker_console.inc
diff --git a/docs/c-api-reference/rainmaker_core.rst b/docs/c-api-reference/rainmaker_core.rst
deleted file mode 100644
index 3a90558..0000000
--- a/docs/c-api-reference/rainmaker_core.rst
+++ /dev/null
@@ -1,18 +0,0 @@
-RainMaker Core
-##############
-
-Core
-----
-.. include:: /_build/inc/esp_rmaker_core.inc
-
-User Mapping
-------------
-.. include:: /_build/inc/esp_rmaker_user_mapping.inc
-
-Scheduling
-----------
-.. include:: /_build/inc/esp_rmaker_schedule.inc
-
-Scenes
-------
-.. include:: /_build/inc/esp_rmaker_scenes.inc
\ No newline at end of file
diff --git a/docs/c-api-reference/rainmaker_mqtt.rst b/docs/c-api-reference/rainmaker_mqtt.rst
deleted file mode 100644
index 08ec66c..0000000
--- a/docs/c-api-reference/rainmaker_mqtt.rst
+++ /dev/null
@@ -1,3 +0,0 @@
-RainMaker MQTT
-##############
-.. include:: /_build/inc/esp_rmaker_mqtt.inc
diff --git a/docs/c-api-reference/rainmaker_ota.rst b/docs/c-api-reference/rainmaker_ota.rst
deleted file mode 100644
index 2a29f0b..0000000
--- a/docs/c-api-reference/rainmaker_ota.rst
+++ /dev/null
@@ -1,3 +0,0 @@
-RainMaker OTA
-#############
-.. include:: /_build/inc/esp_rmaker_ota.inc
diff --git a/docs/c-api-reference/rainmaker_standard_types.rst b/docs/c-api-reference/rainmaker_standard_types.rst
deleted file mode 100644
index 6163fcc..0000000
--- a/docs/c-api-reference/rainmaker_standard_types.rst
+++ /dev/null
@@ -1,18 +0,0 @@
-RainMaker Standard Types
-########################
-
-Standard Types
---------------
-.. include:: /_build/inc/esp_rmaker_standard_types.inc
-
-Standard Parameters
--------------------
-.. include:: /_build/inc/esp_rmaker_standard_params.inc
-
-Standard Devices
-----------------
-.. include:: /_build/inc/esp_rmaker_standard_devices.inc
-
-Standard Services
------------------
-.. include:: /_build/inc/esp_rmaker_standard_services.inc
diff --git a/docs/conf.py b/docs/conf.py
deleted file mode 100644
index 11affa3..0000000
--- a/docs/conf.py
+++ /dev/null
@@ -1,86 +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('.'))
-sys.path.append(os.path.abspath('../cli/'))
-autodoc_mock_imports = ["pathlib", "cryptography", "nvs_partition_gen", "oauth2client", "serial", "user_mapping", "rmaker_tools.rmaker_prov.esp_rainmaker_prov", "rmaker_tools.rmaker_prov.security", "rmaker_tools.rmaker_prov.prov", "rmaker_tools.rmaker_prov.prov_util", "rmaker_tools.rmaker_claim.claim"]
-
-
-# -- Project information -----------------------------------------------------
-
-project = u'ESP RainMaker Programming Guide'
-copyright = u'2020, Espressif Systems (Shanghai) CO., LTD'
-author = 'Espressif'
-
-try:
- builddir = os.environ['BUILDDIR']
-except KeyError:
- builddir = '_build'
-
-def call_with_python(cmd):
- # using sys.executable ensures that the scripts are called with the same Python interpreter
- if os.system('{} {}'.format(sys.executable, cmd)) != 0:
- raise RuntimeError('{} failed'.format(cmd))
-
-
-# Call Doxygen to get XML files from the header files
-print("Calling Doxygen to generate latest XML files")
-if os.system("doxygen Doxyfile") != 0:
- raise RuntimeError('Doxygen call failed')
-
-# Generate 'api_name.inc' files using the XML files by Doxygen
-call_with_python('./gen-dxd.py')
-# -- 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 = [
- 'breathe',
- 'sphinx.ext.autodoc',
- 'link-roles'
-]
-
-# Setup the breathe extension
-breathe_projects = {
- "ESP RainMaker": "./xml"
-}
-breathe_default_project = "ESP RainMaker"
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# 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 = ['_build', 'Thumbs.db', '.DS_Store']
-
-
-# -- 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'
-
-# 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']
-
-html_logo = "_static/esp-rainmaker-logo.png"
-
-def setup(app):
- app.add_stylesheet('theme_overrides.css')
diff --git a/docs/conf_common.py b/docs/conf_common.py
new file mode 100644
index 0000000..9ee30ed
--- /dev/null
+++ b/docs/conf_common.py
@@ -0,0 +1,37 @@
+# -*- coding: utf-8 -*-
+#
+# Common (non-language-specific) configuration for Sphinx
+#
+
+# type: ignore
+# pylint: disable=wildcard-import
+# pylint: disable=undefined-variable
+
+from __future__ import print_function, unicode_literals
+
+from esp_docs.conf_docs import * # noqa: F403,F401
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('.'))
+
+extensions += ['sphinx_copybutton',
+ # Needed as a trigger for running doxygen
+ 'esp_docs.esp_extensions.dummy_build_system',
+ 'esp_docs.esp_extensions.run_doxygen',
+ 'sphinx.ext.autodoc'
+ ]
+
+# link roles config
+github_repo = 'espressif/esp-rainmaker'
+
+# context used by sphinx_idf_theme
+html_context['github_user'] = 'espressif'
+html_context['github_repo'] = 'esp-rainmaker'
+html_static_path = ['../_static']
+
+# Extra options required by sphinx_idf_theme
+project_slug = 'esp-rainmaker'
+
+idf_targets = ['esp32', 'esp32s3', 'esp32c2', 'esp32c3']
+languages = ['en']
diff --git a/docs/c-api-reference/index.rst b/docs/en/c-api-reference/index.rst
similarity index 100%
rename from docs/c-api-reference/index.rst
rename to docs/en/c-api-reference/index.rst
diff --git a/docs/en/c-api-reference/rainmaker_common.rst b/docs/en/c-api-reference/rainmaker_common.rst
new file mode 100644
index 0000000..650d12b
--- /dev/null
+++ b/docs/en/c-api-reference/rainmaker_common.rst
@@ -0,0 +1,18 @@
+RainMaker Common
+################
+
+Utilities
+---------
+.. include-build-file:: inc/esp_rmaker_utils.inc
+
+Factory Storage
+---------------
+.. include-build-file:: inc/esp_rmaker_factory.inc
+
+Work Queue
+----------
+.. include-build-file:: inc/esp_rmaker_work_queue.inc
+
+Common Events
+-------------
+.. include-build-file:: inc/esp_rmaker_common_events.inc
diff --git a/docs/en/c-api-reference/rainmaker_console.rst b/docs/en/c-api-reference/rainmaker_console.rst
new file mode 100644
index 0000000..92b5ef3
--- /dev/null
+++ b/docs/en/c-api-reference/rainmaker_console.rst
@@ -0,0 +1,3 @@
+RainMaker Console
+#################
+.. include-build-file:: inc/esp_rmaker_console.inc
diff --git a/docs/en/c-api-reference/rainmaker_core.rst b/docs/en/c-api-reference/rainmaker_core.rst
new file mode 100644
index 0000000..da5ef6b
--- /dev/null
+++ b/docs/en/c-api-reference/rainmaker_core.rst
@@ -0,0 +1,18 @@
+RainMaker Core
+##############
+
+Core
+----
+.. include-build-file:: inc/esp_rmaker_core.inc
+
+User Mapping
+------------
+.. include-build-file:: inc/esp_rmaker_user_mapping.inc
+
+Scheduling
+----------
+.. include-build-file:: inc/esp_rmaker_schedule.inc
+
+Scenes
+------
+.. include-build-file:: inc/esp_rmaker_scenes.inc
diff --git a/docs/en/c-api-reference/rainmaker_mqtt.rst b/docs/en/c-api-reference/rainmaker_mqtt.rst
new file mode 100644
index 0000000..9c36ef0
--- /dev/null
+++ b/docs/en/c-api-reference/rainmaker_mqtt.rst
@@ -0,0 +1,3 @@
+RainMaker MQTT
+##############
+.. include-build-file:: inc/esp_rmaker_mqtt.inc
diff --git a/docs/en/c-api-reference/rainmaker_ota.rst b/docs/en/c-api-reference/rainmaker_ota.rst
new file mode 100644
index 0000000..a34ca57
--- /dev/null
+++ b/docs/en/c-api-reference/rainmaker_ota.rst
@@ -0,0 +1,3 @@
+RainMaker OTA
+#############
+.. include-build-file:: inc/esp_rmaker_ota.inc
diff --git a/docs/en/c-api-reference/rainmaker_standard_types.rst b/docs/en/c-api-reference/rainmaker_standard_types.rst
new file mode 100644
index 0000000..2d96cf0
--- /dev/null
+++ b/docs/en/c-api-reference/rainmaker_standard_types.rst
@@ -0,0 +1,18 @@
+RainMaker Standard Types
+########################
+
+Standard Types
+--------------
+.. include-build-file:: inc/esp_rmaker_standard_types.inc
+
+Standard Parameters
+-------------------
+.. include-build-file:: inc/esp_rmaker_standard_params.inc
+
+Standard Devices
+----------------
+.. include-build-file:: inc/esp_rmaker_standard_devices.inc
+
+Standard Services
+-----------------
+.. include-build-file:: inc/esp_rmaker_standard_services.inc
diff --git a/docs/en/conf.py b/docs/en/conf.py
new file mode 100644
index 0000000..0554e57
--- /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
+
+sys.path.append(os.path.abspath('../../cli/'))
+autodoc_mock_imports = ["pathlib", "cryptography", "nvs_partition_gen", "oauth2client", "serial", "user_mapping", "rmaker_tools.rmaker_prov.esp_rainmaker_prov", "rmaker_tools.rmaker_prov.security", "rmaker_tools.rmaker_prov.prov", "rmaker_tools.rmaker_prov.prov_util", "rmaker_tools.rmaker_claim.claim"]
+
+current_year = datetime.datetime.now().year
+# -- Project information -----------------------------------------------------
+
+project = u'ESP RainMaker Programming Guide'
+copyright = u'2020, Espressif Systems (Shanghai) CO., LTD'
+author = 'Espressif'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+language = 'en'
diff --git a/docs/en/index.rst b/docs/en/index.rst
new file mode 100644
index 0000000..7908057
--- /dev/null
+++ b/docs/en/index.rst
@@ -0,0 +1,14 @@
+ESP RainMaker Programming Guide
+===============================
+ESP RainMaker is an end-to-end solution offered by Espressif to enable remote control and monitoring for products based on ESP32 series of SoCs (e.g., ESP32, ESP32-S2, ESP32-C3, ESP32-C6, ESP32-C2, etc.) without any configuration required in the Cloud. It provides a device SDK, self-adapting phone apps, transparent cloud middleware and host utilities to reduce complexity in development of connected devices.
+
+This is the C API (for firmware) and Python API (for host tools) documentation for ESP RainMaker. All other documentation can be found at `http://rainmaker.espressif.com `_
+
+.. _C API Reference: c-api-reference/index.html
+.. _Python API Reference: python-api-reference/index.html
+
+.. toctree::
+ :hidden:
+
+ c-api-reference/index
+ python-api-reference/index
diff --git a/docs/python-api-reference/cmd.rst b/docs/en/python-api-reference/cmd.rst
similarity index 100%
rename from docs/python-api-reference/cmd.rst
rename to docs/en/python-api-reference/cmd.rst
diff --git a/docs/python-api-reference/index.rst b/docs/en/python-api-reference/index.rst
similarity index 100%
rename from docs/python-api-reference/index.rst
rename to docs/en/python-api-reference/index.rst
diff --git a/docs/python-api-reference/lib.rst b/docs/en/python-api-reference/lib.rst
similarity index 100%
rename from docs/python-api-reference/lib.rst
rename to docs/en/python-api-reference/lib.rst
diff --git a/docs/gen-dxd.py b/docs/gen-dxd.py
deleted file mode 100755
index a87c940..0000000
--- a/docs/gen-dxd.py
+++ /dev/null
@@ -1,318 +0,0 @@
-#!/usr/bin/env python
-#
-# gen-dxd.py - Generate Doxygen Directives
-#
-# This code is in the Public Domain (or CC0 licensed, at your option.)
-# Unless required by applicable law or agreed to in writing, this
-# software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
-# CONDITIONS OF ANY KIND, either express or implied.
-#
-
-from __future__ import print_function
-from __future__ import unicode_literals
-from builtins import range
-from io import open
-import sys
-import os
-import re
-
-# Determime build directory
-builddir = '_build'
-if 'BUILDDIR' in os.environ:
- builddir = os.environ['BUILDDIR']
-
-# Script configurationheader_file_path_prefix = "../../components/"
-header_file_path_prefix = "components/"
-"""string: path prefix for header files.
-"""
-doxyfile_path = "Doxyfile"
-"""string: path to a file containing header files to processs.
-"""
-xml_directory_path = "xml"
-"""string: path to directory with XML files by Doxygen.
-"""
-inc_directory_path = os.path.join(builddir, 'inc')
-"""string: path prefix for header files.
-"""
-all_kinds = [
- ("function", "Functions"),
- ("union", "Unions"),
- ("struct", "Structures"),
- ("define", "Macros"),
- ("typedef", "Type Definitions"),
- ("enum", "Enumerations")
-]
-"""list of items that will be generated for a single API file
-"""
-
-
-def get_doxyfile_input():
- """Get contents of Doxyfile's INPUT statement.
-
- Returns:
- Contents of Doxyfile's INPUT.
-
- """
- if not os.path.isfile(doxyfile_path):
- print("Doxyfile '%s' does not exist!" % doxyfile_path)
- sys.exit()
-
- print("Getting Doxyfile's INPUT")
-
- input_file = open(doxyfile_path, "r", encoding='utf-8')
-
- line = input_file.readline()
- # read contents of Doxyfile until 'INPUT' statement
- while line:
- if line.find("INPUT") == 0:
- break
- line = input_file.readline()
-
- doxyfile_INPUT = ""
- line = input_file.readline()
- # skip input_file contents until end of 'INPUT' statement
- while line:
- if line.isspace():
- # we have reached the end of 'INPUT' statement
- break
- # process only lines that are not comments
- if line.find("#") == -1:
- # extract header file path inside components folder
- m = re.search(header_file_path_prefix + "(.*\.h)", line) # noqa: W605 - regular expression
- header_file_path = m.group(1)
- doxyfile_INPUT += header_file_path + "\n"
- # proceed reading next line
- line = input_file.readline()
-
- input_file.close()
- return doxyfile_INPUT
-
-
-def get_api_name(header_file_path):
- """Get name of API from header file path.
-
- Args:
- header_file_path: path to the header file.
-
- Returns:
- The name of API.
-
- """
- api_name = ""
- regex = r".*/(.*)\.h"
- m = re.search(regex, header_file_path)
- if m:
- api_name = m.group(1)
-
- return api_name
-
-
-def get_rst_header(header_name):
- """Get rst formatted code with a header.
-
- Args:
- header_name: name of header.
-
- Returns:
- Formatted rst code with the header.
-
- """
-
- rst_output = ""
- rst_output += header_name + "\n"
- rst_output += "^" * len(header_name) + "\n"
- rst_output += "\n"
-
- return rst_output
-
-
-def select_unions(innerclass_list):
- """Select unions from innerclass list.
-
- Args:
- innerclass_list: raw list with unions and structures
- extracted from Dogygen's xml file.
-
- Returns:
- Doxygen directives with unions selected from the list.
-
- """
-
- rst_output = ""
- for line in innerclass_list.splitlines():
- # union is denoted by "union" at the beginning of line
- if line.find("union") == 0:
- union_id, union_name = re.split(r"\t+", line)
- rst_output += ".. doxygenunion:: "
- rst_output += union_name
- rst_output += "\n"
-
- return rst_output
-
-
-def select_structs(innerclass_list):
- """Select structures from innerclass list.
-
- Args:
- innerclass_list: raw list with unions and structures
- extracted from Dogygen's xml file.
-
- Returns:
- Doxygen directives with structures selected from the list.
- Note: some structures are excluded as described on code below.
-
- """
-
- rst_output = ""
- for line in innerclass_list.splitlines():
- # structure is denoted by "struct" at the beginning of line
- if line.find("struct") == 0:
- # skip structures that are part of union
- # they are documented by 'doxygenunion' directive
- if line.find("::") > 0:
- continue
- struct_id, struct_name = re.split(r"\t+", line)
- rst_output += ".. doxygenstruct:: "
- rst_output += struct_name
- rst_output += "\n"
- rst_output += " :members:\n"
- rst_output += "\n"
-
- return rst_output
-
-
-def get_directives(tree, kind):
- """Get directives for specific 'kind'.
-
- Args:
- tree: the ElementTree 'tree' of XML by Doxygen
- kind: name of API "kind" to be generated
-
- Returns:
- Doxygen directives for selected 'kind'.
- Note: the header with "kind" name is included.
-
- """
-
- rst_output = ""
- if kind in ["union", "struct"]:
- innerclass_list = ""
- for elem in tree.iterfind('compounddef/innerclass'):
- innerclass_list += elem.attrib["refid"] + "\t" + elem.text + "\n"
- if kind == "union":
- rst_output += select_unions(innerclass_list)
- else:
- rst_output += select_structs(innerclass_list)
- else:
- for elem in tree.iterfind(
- 'compounddef/sectiondef/memberdef[@kind="%s"]' % kind):
- name = elem.find('name')
- rst_output += ".. doxygen%s:: " % kind
- rst_output += name.text + "\n"
- if rst_output:
- all_kinds_dict = dict(all_kinds)
- rst_output = get_rst_header(all_kinds_dict[kind]) + rst_output + "\n"
-
- return rst_output
-
-
-def generate_directives(header_file_path):
- """Generate API reference with Doxygen directives for a header file.
-
- Args:
- header_file_path: a path to the header file with API.
-
- Returns:
- Doxygen directives for the header file.
-
- """
-
- api_name = get_api_name(header_file_path)
-
- # in XLT file name each "_" in the api name is expanded by Doxygen to "__"
- xlt_api_name = api_name.replace("_", "__")
- xml_file_path = "%s/%s_8h.xml" % (xml_directory_path, xlt_api_name)
-
- rst_output = ""
- rst_output = ".. File automatically generated by 'gen-dxd.py'\n"
- rst_output += "\n"
- rst_output += get_rst_header("Header File")
- rst_output += "* :component_file:`" + header_file_path + "`\n"
- rst_output += "\n"
-
- try:
- import xml.etree.cElementTree as ET
- except ImportError:
- import xml.etree.ElementTree as ET
-
- tree = ET.ElementTree(file=xml_file_path)
- for i in range(len(all_kinds)):
- kind = all_kinds[i][0]
- rst_output += get_directives(tree, kind)
-
- return rst_output
-
-
-def generate_api_inc_files():
- """Generate header_file.inc files
- with API reference made of doxygen directives
- for each header file
- specified in the 'INPUT' statement of Doxyfile.
-
- """
-
- if not os.path.isdir(xml_directory_path):
- print("Directory %s does not exist!" % xml_directory_path)
- sys.exit()
-
- if not os.path.exists(inc_directory_path):
- os.makedirs(inc_directory_path)
-
- list_to_generate = get_doxyfile_input()
- print("Generating 'api_name.inc' files with Doxygen directives")
- for header_file_path in list_to_generate.splitlines():
- api_name = get_api_name(header_file_path)
- inc_file_path = inc_directory_path + "/" + api_name + ".inc"
- rst_output = generate_directives(header_file_path)
-
- previous_rst_output = ''
- if os.path.isfile(inc_file_path):
- with open(inc_file_path, "r", encoding='utf-8') as inc_file_old:
- previous_rst_output = inc_file_old.read()
-
- if previous_rst_output != rst_output:
- with open(inc_file_path, "w", encoding='utf-8') as inc_file:
- inc_file.write(rst_output)
-
-
-if __name__ == "__main__":
- """The main script that generates
- Doxygen directives.
-
- """
-
- # Process command line arguments, if any
- if len(sys.argv) > 1:
- if not os.path.isdir(xml_directory_path):
- print("Directory %s does not exist!" % xml_directory_path)
- sys.exit()
- header_file_path = sys.argv[1]
- api_name = get_api_name(header_file_path)
- if api_name:
- rst_output = generate_directives(header_file_path)
- print("Doxygen directives for '%s'" % header_file_path)
- print()
- print(rst_output)
- else:
- print("Options to execute 'gen-dxd.py' application:")
- print("1: $ python gen-dxd.py")
- print(" Generate API 'header_file.inc' files for headers defined in '%s'" % doxyfile_path)
- print("2: $ python gen-dxd.py header_file_path")
- print(" Print out Doxygen directives for a single header file")
- print(" example: $ python gen-dxd.py mdns/include/mdns.h")
- print(" NOTE: Run Doxygen first to get XML files for the header file")
-
- sys.exit()
-
- # No command line arguments given
- generate_api_inc_files()
diff --git a/docs/index.rst b/docs/index.rst
deleted file mode 100644
index 12ef45d..0000000
--- a/docs/index.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-ESP RainMaker Programming Guide
-===============================
-ESP RainMaker is a platform that allows developers to build connected devices with Espressif’s ESP32-S2 SoC without hassle of managing the infrastructure. It provides a device SDK, self-adapting phone apps, transparent cloud middleware and host utilities to reduce complexity in development of connected devices.
-
-This is the C API (for firmware) and Python API (for host tools) documentation for ESP RainMaker. All other documentation can be found at `http://rainmaker.espressif.com `_
-
-.. toctree::
- :maxdepth: 2
-
- C API Reference
- Python API Reference
diff --git a/docs/link-roles.py b/docs/link-roles.py
deleted file mode 100644
index a25a9ca..0000000
--- a/docs/link-roles.py
+++ /dev/null
@@ -1,66 +0,0 @@
-# based on http://protips.readthedocs.io/link-roles.html
-
-from __future__ import print_function
-from __future__ import unicode_literals
-import re
-import os
-from docutils import nodes
-from local_util import run_cmd_get_output
-
-
-def get_github_rev():
- path = run_cmd_get_output('git rev-parse --short HEAD')
- tag = run_cmd_get_output('git describe --exact-match')
- print('Git commit ID: ', path)
- if len(tag):
- print('Git tag: ', tag)
- path = tag
- return path
-
-
-def setup(app):
- rev = get_github_rev()
-
- # links to files or folders on the GitHub
- baseurl = 'https://github.com/espressif/esp-rainmaker'
- app.add_role('component_file', autolink('{}/blob/{}/components/%s'.format(baseurl, rev)))
-
- # link to the current documentation file in specific language version
- on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
- if on_rtd:
- # provide RTD specific commit identification to be included in the link
- tag_rev = 'latest'
- if (run_cmd_get_output('git rev-parse --short HEAD') != rev):
- tag_rev = rev
- else:
- # if not on the RTD then provide generic identification
- tag_rev = run_cmd_get_output('git describe --always')
-
- app.add_role('link_to_translation', crosslink('%s../../%s/{}/%s.html'.format(tag_rev)))
-
-
-def autolink(pattern):
- def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
- m = re.search('(.*)\s*<(.*)>', text) # noqa: W605 - regular expression
- if m:
- link_text = m.group(1)
- link = m.group(2)
- else:
- link_text = text
- link = text
- url = pattern % (link,)
- node = nodes.reference(rawtext, link_text, refuri=url, **options)
- return [node], []
- return role
-
-
-def crosslink(pattern):
- def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
- (language, link_text) = text.split(':')
- docname = inliner.document.settings.env.docname
- doc_path = inliner.document.settings.env.doc2path(docname, None, None)
- return_path = '../' * doc_path.count('/')
- url = pattern % (return_path, language, docname)
- node = nodes.reference(rawtext, link_text, refuri=url, **options)
- return [node], []
- return role
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 73c8259..498bb28 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,6 +1,4 @@
# This is a list of python packages used to generate documentation. This file is used with pip:
# pip install --user -r requirements.txt
#
-sphinx==2.3.1
-breathe==4.14.1
-sphinx_rtd_theme # This theme is no longer a hard dependency since version 1.4.0. Need to install it manually.
+esp-docs==0.2.4
diff --git a/docs/utils.sh b/docs/utils.sh
new file mode 100644
index 0000000..84f3748
--- /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
+}