ASIO: Initial version based on IDF 5.0 with history

components/asio/docs/Doxyfile

@@ -0,0 +1,73 @@
+# This is Doxygen configuration file
+#
+# Doxygen provides over 260 configuration statements
+# To make this file easier to follow,
+# it contains only statements that are non-default
+#
+# NOTE:
+# It is recommended not to change defaults unless specifically required
+# Test any changes how they affect generated documentation
+# Make sure that correct warnings are generated to flag issues with documented code
+#
+# For the complete list of configuration statements see:
+# http://doxygen.nl/manual/config.html
+
+
+PROJECT_NAME = "ESP Protocols Programming Guide"
+
+## The 'INPUT' statement below is used as input by script 'gen-df-input.py'
+## to automatically generate API reference list files heder_file.inc
+## These files are placed in '_inc' directory
+## and used to include in API reference documentation
+
+
+## Get warnings for functions that have no documentation for their parameters or return value
+##
+WARN_NO_PARAMDOC = YES
+
+## Enable preprocessing and remove __attribute__(...) expressions from the INPUT files
+##
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+PREDEFINED             = \
+    $(ENV_DOXYGEN_DEFINES) \
+    __DOXYGEN__=1 \
+    __attribute__(x)= \
+	_Static_assert()= \
+    IDF_DEPRECATED(X)= \
+    IRAM_ATTR= \
+    configSUPPORT_DYNAMIC_ALLOCATION=1 \
+    configSUPPORT_STATIC_ALLOCATION=1 \
+    configQUEUE_REGISTRY_SIZE=1 \
+    configUSE_RECURSIVE_MUTEXES=1 \
+    configTHREAD_LOCAL_STORAGE_DELETE_CALLBACKS=1 \
+    configNUM_THREAD_LOCAL_STORAGE_POINTERS=1 \
+    configUSE_APPLICATION_TASK_TAG=1 \
+    configTASKLIST_INCLUDE_COREID=1 \
+    "ESP_EVENT_DECLARE_BASE(x)=extern esp_event_base_t x"
+
+## Do not complain about not having dot
+##
+HAVE_DOT = NO
+
+## Generate XML that is required for Breathe
+##
+GENERATE_XML    = YES
+XML_OUTPUT      = xml
+
+GENERATE_HTML   = NO
+HAVE_DOT        = NO
+GENERATE_LATEX  = NO
+GENERATE_MAN    = YES
+GENERATE_RTF    = NO
+
+## Skip distracting progress messages
+##
+QUIET = YES
+
+## Enable Section Tags for conditional documentation
+##
+ENABLED_SECTIONS += \
+    DOC_EXCLUDE_HEADER_SECTION \   ## To conditionally remove doc sections from IDF source files without affecting documentation in upstream files.
+    DOC_SINGLE_GROUP        ## To conditionally remove groups from the documentation and create a 'flat' document without affecting documentation in upstream files.

components/asio/docs/conf_common.py

@@ -0,0 +1,21 @@
+from esp_docs.conf_docs import *  # noqa: F403,F401
+
+extensions += ['sphinx_copybutton',
+               # Needed as a trigger for running doxygen
+               'esp_docs.esp_extensions.dummy_build_system',
+               'esp_docs.esp_extensions.run_doxygen',
+               ]
+
+# link roles config
+github_repo = 'espressif/esp-protocols'
+
+# context used by sphinx_idf_theme
+html_context['github_user'] = 'espressif'
+html_context['github_repo'] = 'esp-protocols'
+
+# Extra options required by sphinx_idf_theme
+project_slug = 'esp-idf' # >=5.0
+versions_url = 'https://github.com/espressif/esp-protocols/docs/docs_versions.js'
+
+idf_targets = ['esp32']
+languages = ['en', 'zh_CN']

components/asio/docs/en/conf.py

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+#
+# English Language RTD & Sphinx config file
+#
+# Uses ../conf_common.py for most non-language-specific settings.
+
+# Importing conf_common adds all the non-language-specific
+# parts to this conf module
+
+try:
+    from conf_common import *  # noqa: F403,F401
+except ImportError:
+    import os
+    import sys
+    sys.path.insert(0, os.path.abspath('../'))
+    from conf_common import *  # noqa: F403,F401
+
+# General information about the project.
+project = u'ESP-Protocols'
+copyright = u'2016 - 2022, Espressif Systems (Shanghai) Co., Ltd'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+language = 'en'

components/asio/docs/en/index.rst

@@ -0,0 +1,42 @@
+ASIO port
+=========
+
+Overview
+--------
+Asio is a cross-platform C++ library, see https://think-async.com/Asio/. It provides a consistent asynchronous model using a modern C++ approach.
+
+
+ASIO documentation
+^^^^^^^^^^^^^^^^^^
+Please refer to the original asio documentation at https://think-async.com/Asio/Documentation.
+Asio also comes with a number of examples which could be find under Documentation/Examples on that web site.
+
+Supported features
+^^^^^^^^^^^^^^^^^^
+ESP platform port currently supports only network asynchronous socket operations; does not support serial port.
+SSL/TLS support is disabled by default and could be enabled in component configuration menu by choosing TLS library from
+
+- mbedTLS with OpenSSL translation layer (default option)
+- wolfSSL
+
+SSL support is very basic at this stage and it does include following features:
+
+- Verification callbacks
+- DH property files
+- Certificates/private keys file APIs
+
+Internal asio settings for ESP include
+
+- EXCEPTIONS are enabled in ASIO if enabled in menuconfig
+- TYPEID is enabled in ASIO if enabled in menuconfig
+
+Application Example
+-------------------
+ESP examples are based on standard asio :example:`examples <../examples>`:
+
+- :example:`udp_echo_server <../examples/udp_echo_server>`
+- :example:`tcp_echo_server <../examples/tcp_echo_server>`
+- :example:`asio_chat <../examples/asio_chat>`
+- :example:`ssl_client_server <../examples/ssl_client_server>`
+
+Please refer to the specific example README.md for details

components/asio/docs/generate_docs

@@ -0,0 +1,27 @@
+build-docs --target esp32 --language en
+
+cp -rf _build/en/esp32/html .
+rm -rf _build __pycache__
+
+# Modifes some version and target fields of index.html
+echo "<script type="text/javascript">
+window.onload =(function() {
+    var myAnchor = document.getElementById('version-select');
+    var mySpan = document.createElement('input');
+    mySpan.setAttribute('type', 'text');
+    mySpan.setAttribute('maxLength', '10');
+    mySpan.value = 'latest';
+    mySpan.setAttribute('disabled', true);
+    myAnchor.parentNode.replaceChild(mySpan, myAnchor);
+ 
+    var myAnchor = document.getElementById('target-select');
+    var mySpan = document.createElement('input');
+    mySpan.setAttribute('type', 'text');
+    mySpan.setAttribute('maxLength', '10');
+    mySpan.value = 'all targets';
+    mySpan.setAttribute('disabled', true);
+    myAnchor.parentNode.replaceChild(mySpan, myAnchor);
+
+})();
+</script>" >> html/index.html
+

components/asio/docs/zh_CN/conf.py

@@ -0,0 +1,27 @@
+# -*- 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'ESP-IDF 编程指南'
+copyright = u'2016 - {} 乐鑫信息科技（上海）股份有限公司'.format(current_year)
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+language = 'zh_CN'

components/asio/docs/zh_CN/index.rst

@@ -0,0 +1 @@
+.. include:: ../../../en/api-reference/protocols/asio.rst