diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index f72c14e..cec5a7d 100644 --- a/.github/workflows/docs.yml +++ b/.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 diff --git a/.gitignore b/.gitignore index 149d9da..4ef7f72 100644 --- a/.gitignore +++ b/.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 diff --git a/README.md b/README.md index 1ab460f..4809c67 100644 --- a/README.md +++ b/README.md @@ -2,17 +2,17 @@
-[![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 development platform for IoT modules manufactured by Tuya Inc. diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 0000000..7497621 --- /dev/null +++ b/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) diff --git a/arduino/libretuya/api/LibreTuyaAPI.h b/arduino/libretuya/api/LibreTuyaAPI.h index ab166b9..f3c016f 100644 --- a/arduino/libretuya/api/LibreTuyaAPI.h +++ b/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 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..0853199 --- /dev/null +++ b/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). diff --git a/docs/libs-built-in.md b/docs/libs-built-in.md index f943ae1..cdf1c29 100644 --- a/docs/libs-built-in.md +++ b/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) diff --git a/docs/reference/lt-api.md b/docs/reference/lt-api.md new file mode 100644 index 0000000..8a84e15 --- /dev/null +++ b/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 +%} diff --git a/docs/requirements.txt b/docs/requirements.txt index fbee236..46f4c85 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index cf6b277..675284f 100644 --- a/mkdocs.yml +++ b/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"