[docs] Add Doxygen

.github/workflows/docs.yml

@@ -1,11 +1,12 @@
 name: Deploy docs on GitHub Pages
+
 on:
   push:
     branches:
       - master
 
 jobs:
-  build:
+  docs:
     name: Deploy docs
     runs-on: ubuntu-latest
     steps:
@@ -17,5 +18,5 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           CONFIG_FILE: mkdocs.yml
-          EXTRA_PACKAGES: build-base
+          EXTRA_PACKAGES: build-base doxygen
           REQUIREMENTS: docs/requirements.txt

.gitignore

@@ -252,3 +252,9 @@ cython_debug/
 # End of https://www.toptal.com/developers/gitignore/api/c,c++,visualstudiocode,python
 
 .vscode/settings.json
+
+# mkdocs
+xml/
+ltapi/
+ltambz/
+hashChanges.yaml

README.md

@@ -2,17 +2,17 @@
 
 <div align="center" markdown>
 
-[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/kuba2k2/libretuya/docs?label=docs)](https://kuba2k2.github.io/libretuya/)
-![GitHub last commit](https://img.shields.io/github/last-commit/kuba2k2/libretuya)
+[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/kuba2k2/libretuya/Deploy%20docs%20on%20GitHub%20Pages?label=docs&logo=markdown)](https://kuba2k2.github.io/libretuya/)
+![GitHub last commit](https://img.shields.io/github/last-commit/kuba2k2/libretuya?logo=github)
 
-[![Code style: clang-format](https://img.shields.io/badge/code%20style-clang--format-purple.svg)](https://github.com/psf/black)
+[![Code style: clang-format](https://img.shields.io/badge/code%20style-clang--format-purple.svg)](.clang-format)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
 [![Discord](https://img.shields.io/discord/967863521511608370?color=%235865F2&label=Discord&logo=discord&logoColor=white)](https://discord.gg/SyGCB9Xwtf)
+[![PlatformIO Registry](https://badges.registry.platformio.org/packages/kuba2k2/platform/libretuya.svg)](https://registry.platformio.org/platforms/kuba2k2/libretuya)
 
 ![RTL8710BN](https://img.shields.io/badge/-rtl8710bn-blue)
 
-<!-- [![PlatformIO Registry](https://badges.registry.platformio.org/packages/kuba2k2/platform/libretuya.svg)](https://registry.platformio.org/platforms/kuba2k2/libretuya) -->
 </div>
 
 PlatformIO development platform for IoT modules manufactured by Tuya Inc.

SUMMARY.md

@@ -0,0 +1,42 @@
+* [Home](README.md)
+* [Configuration](docs/config.md)
+* Reference
+	* [LibreTuya API](docs/reference/lt-api.md)
+		* [Class reference](ltapi/class_libre_tuya.md)
+		* [Static functions](ltapi/_libre_tuya_a_p_i_8cpp.md)
+		* [Logger](ltapi/lt__logger_8h.md)
+	* Common API
+		* [Flash](ltapi/class_i_flash_class.md)
+		* [FS](ltapi/classfs_1_1_f_s.md)
+		* [Preferences](ltapi/class_i_preferences.md)
+		* [WiFi API](ltapi/class_i_wi_fi_generic_class.md)
+			* [Station](ltapi/class_i_wi_fi_s_t_a_class.md)
+			* [Access Point](ltapi/class_i_wi_fi_a_p_class.md)
+			* [Scanning](ltapi/class_i_wi_fi_scan_class.md)
+			* [TCP Client](ltapi/class_i_wi_fi_client.md)
+			* [SSL Client](ltapi/class_i_wi_fi_client_secure.md)
+			* [TCP Server](ltapi/class_i_wi_fi_server.md)
+	* [LibreTuya libraries](docs/libs-built-in.md)
+		* [base64](ltapi/classbase64.md)
+		* [HTTPClient](ltapi/class_h_t_t_p_client.md)
+		* NetUtils
+			* [ssl/MbedTLSClient](ltapi/class_mbed_t_l_s_client.md)
+			* [IPv6Address](ltapi/classarduino_1_1_i_pv6_address.md)
+			* [LwIPRxBuffer](ltapi/class_lw_i_p_rx_buffer.md)
+		* [WebServer](ltapi/class_web_server.md)
+		* [WiFiMulti](ltapi/class_wi_fi_multi.md)
+	* [Third party libraries](docs/libs-3rd-party.md)
+	* Full documentation
+		* [Classes](ltapi/classes.md)
+		* [Functions](ltapi/functions.md)
+		* [Macros](ltapi/macros.md)
+		* [File list](ltapi/files.md)
+* Platforms
+	* Realtek AmebaZ Series
+		* Boards
+			* [WR3](boards/wr3/README.md)
+		* C library
+			* [Built-in functions](docs/platform/realtek-ambz/stdlib.md)
+			* [Memory management](docs/platform/realtek-ambz/memory-management.md)
+		* [Debugging](docs/platform/realtek/debugging.md)
+		* [Exception decoder](docs/platform/realtek/exception-decoder.md)

arduino/libretuya/api/LibreTuyaAPI.h

@@ -49,3 +49,26 @@ extern char *strdup(const char *);
 #ifdef __cplusplus
 String ipToString(const IPAddress &ip);
 #endif
+
+// Main class
+#ifdef __cplusplus
+/**
+ * @brief Main LibreTuya API class.
+ *
+ * This class contains all functions common amongst all platforms.
+ * Implementations of these methods may vary between platforms.
+ *
+ * The class is accessible using the `LT` global object (defined by the platform).
+ */
+class LibreTuya {
+
+	/* Common methods*/
+
+  public:
+	/* Platform-defined methods */
+
+  public:
+};
+
+extern LibreTuya LT;
+#endif

docs/README.md

@@ -0,0 +1,7 @@
+# Documentation
+
+This documentation is best suited for rendering with MkDocs. Some elements may not display correctly in the GitHub markdown reader.
+
+Please visit [https://kuba2k2.github.io/libretuya/](https://kuba2k2.github.io/libretuya) for the full experience.
+
+If you still want to read the docs on GitHub, visit [SUMMARY.md](../SUMMARY.md).

docs/libs-built-in.md

@@ -3,20 +3,35 @@
 
 ## base64
 - [Source](https://github.com/espressif/arduino-esp32/blob/master/cores/esp32/base64.cpp): ESP32 Arduino Core
-- [API](../arduino/libretuya/libraries/base64/base64.h)
+- [Reference](../ltapi/classbase64.md)
 
 Helper base64 encoder used in some libs taken from ESP32.
 
 ## HTTPClient
 - [Source](https://github.com/espressif/arduino-esp32/tree/master/libraries/HTTPClient): ESP32 Arduino Core
-- [API](../arduino/libretuya/libraries/HTTPClient/HTTPClient.h)
+- [Reference](../ltapi/class_h_t_t_p_client.md)
 - [Examples](https://github.com/espressif/arduino-esp32/tree/master/libraries/HTTPClient/examples)
 
-HTTP(S) client. Some reference may be found here: [https://links2004.github.io/Arduino/dd/d8d/class_h_t_t_p_client.html](https://links2004.github.io/Arduino/dd/d8d/class_h_t_t_p_client.html).
+HTTP(S) client.
+
+## NetUtils
+
+Utilities and common classes related to network.
+
+- [ssl/MbedTLSClient.cpp](../ltapi/class_mbed_t_l_s_client.md) ([source](https://github.com/espressif/arduino-esp32/tree/master/libraries/WiFiClientSecure/src): ESP32 WiFiClientSecure)
+- [IPv6Address.cpp](../ltapi/classarduino_1_1_i_pv6_address.md) ([source](https://github.com/espressif/arduino-esp32/blob/master/cores/esp32/IPv6Address.cpp): ESP32 IPv6Address)
+- [LwIPRxBuffer.cpp](../ltapi/class_lw_i_p_rx_buffer.md) ([source](https://github.com/espressif/arduino-esp32/blob/master/libraries/WiFi/src/WiFiClient.cpp): ESP32 WiFiClient)
+
+## WebServer
+- [Source](https://github.com/espressif/arduino-esp32/tree/master/libraries/WebServer/src): ESP32 Arduino Core
+- [Reference](../ltapi/class_web_server.md)
+- Examples:
+    - [HelloServer](https://github.com/espressif/arduino-esp32/blob/master/libraries/WebServer/examples/HelloServer/HelloServer.ino)
+    - [MultiHomedServers](https://github.com/espressif/arduino-esp32/blob/master/libraries/WebServer/examples/MultiHomedServers/MultiHomedServers.ino)
 
 ## WiFiMulti
 - [Source](https://github.com/espressif/arduino-esp32/tree/master/libraries/WiFi/src): ESP32 Arduino Core
-- [API](../arduino/libretuya/libraries/WiFiMulti/WiFiMulti.h)
+- [Reference](../ltapi/class_wi_fi_multi.md)
 - [Docs](https://docs.espressif.com/projects/arduino-esp32/en/latest/api/wifi.html#wifimulti)
 - Examples:
     - [WiFiMulti](https://github.com/espressif/arduino-esp32/blob/master/libraries/WiFi/examples/WiFiMulti/WiFiMulti.ino)

docs/reference/lt-api.md

@@ -0,0 +1,41 @@
+# LibreTuya API
+
+## Class functions
+
+{%
+   include-markdown "../../ltapi/class_libre_tuya.md"
+   start="(class_libre_tuya.md)\n"
+   end="[More...]"
+%}
+
+{%
+   include-markdown "../../ltapi/class_libre_tuya.md"
+   start="# Detailed Description\n"
+   end="## Public Functions Documentation\n"
+%}
+
+{%
+   include-markdown "../../ltapi/class_libre_tuya.md"
+   start="## Public Functions\n"
+   end="# Detailed Description\n"
+%}
+
+## Static
+
+### Public Attributes
+
+{%
+   include-markdown "../../ltapi/_libre_tuya_a_p_i_8h.md"
+   start="## Public Attributes\n"
+   end="## Public Attributes Documentation\n"
+   heading-offset=1
+%}
+
+## Logger
+
+{%
+   include-markdown "../../ltapi/lt__logger_8h.md"
+   start="## Public Functions\n"
+   end="## Public Functions Documentation\n"
+   heading-offset=1
+%}

docs/requirements.txt

@@ -1 +1,5 @@
 mkdocs-same-dir
+mkdocs-literate-nav
+mkdocs-section-index
+mkdocs-include-markdown-plugin
+-e git+https://github.com/kuba2k2/mkdoxy

mkdocs.yml

@@ -1,26 +1,30 @@
 site_name: LibreTuya
 docs_dir: .
+
 site_url: https://kuba2k2.github.io/libretuya/
 repo_url: https://github.com/kuba2k2/libretuya
+
 theme:
   name: material
+
 plugins:
   - same-dir
+  - mkdoxy:
+      projects:
+        # project names must be alphanumeric, else snippets won't work
+        ltapi:
+          src-dirs: arduino/libretuya/
+          doxy-cfg:
+            PREDEFINED: __cplusplus
+        ltambz:
+          src-dirs: arduino/realtek-ambz/
+          doxy-cfg:
+            PREDEFINED: __cplusplus
+      save-api: .
+  - literate-nav:
+      nav_file: SUMMARY.md
+  - section-index
+  - include-markdown
+
 markdown_extensions:
   - md_in_html
-
-nav:
-  - "Home": "README.md"
-  - "Configuration": "docs/config.md"
-  - "Libraries":
-      - "Built-in": "docs/libs-built-in.md"
-      - "Third party": "docs/libs-3rd-party.md"
-  - "Platforms":
-      - "Realtek AmebaZ Series":
-          - "Boards":
-              - "WR3": "boards/wr3/README.md"
-          - "C library":
-              - "Built-in functions": "docs/platform/realtek-ambz/stdlib.md"
-              - "Memory management": "docs/platform/realtek-ambz/memory-management.md"
-          - "Debugging": "docs/platform/realtek/debugging.md"
-          - "Exception decoder": "docs/platform/realtek/exception-decoder.md"