From 470eb640517cfb8da90dba0cbacf2d7ccba6c4da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kuba=20Szczodrzy=C5=84ski?= Date: Fri, 29 Apr 2022 23:16:32 +0200 Subject: [PATCH] [docs] Migrate to mkdocs --- .github/workflows/docs.yml | 21 +++++++++++++++++ README.md | 8 +++++-- boards/wr3/README.md | 2 +- docs/README.md | 11 --------- docs/{API Configuration.md => config.md} | 2 +- docs/{Libraries.md => libs-3rd-party.md} | 0 .../{libraries/README.md => libs-built-in.md} | 10 ++++---- ...eption decoder.md => exception-decoder.md} | 0 docs/requirements.txt | 1 + mkdocs.yml | 23 +++++++++++++++++++ 10 files changed, 58 insertions(+), 20 deletions(-) create mode 100644 .github/workflows/docs.yml delete mode 100644 docs/README.md rename docs/{API Configuration.md => config.md} (92%) rename docs/{Libraries.md => libs-3rd-party.md} (100%) rename docs/{libraries/README.md => libs-built-in.md} (67%) rename docs/platform/realtek/{Exception decoder.md => exception-decoder.md} (100%) create mode 100644 docs/requirements.txt create mode 100644 mkdocs.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..f72c14e --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,21 @@ +name: Deploy docs on GitHub Pages +on: + push: + branches: + - master + +jobs: + build: + name: Deploy docs + runs-on: ubuntu-latest + steps: + - name: Checkout main + uses: actions/checkout@v2 + + - name: Deploy docs + uses: mhausenblas/mkdocs-deploy-gh-pages@master + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + CONFIG_FILE: mkdocs.yml + EXTRA_PACKAGES: build-base + REQUIREMENTS: docs/requirements.txt diff --git a/README.md b/README.md index afb5dac..63fd91d 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # LibreTuya -
+
[![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) @@ -25,7 +25,7 @@ LibreTuya also provides a common interface for all platform implementations. The 1. [Install PlatformIO](https://platformio.org/platformio-ide) 2. `platformio platform install libretuya` 3. Create a project, build it and upload! -4. See the [docs](docs/README.md) for any questions/problems. +4. See the [docs](https://kuba2k2.github.io/libretuya/) for any questions/problems. ## Board List @@ -133,12 +133,14 @@ Platform name | Supported MCU(s) ### Realtek Ameba The logic behind naming of Realtek chips and their series took me some time to figure out: + - RTL8xxxA - Ameba1/Ameba Series - RTL8xxxB - AmebaZ Series - RTL8xxxC - AmebaZ2/ZII Series - RTL8xxxD - AmebaD Series As such, there are numerous CPUs with the same numbers but different series, which makes them require different code and SDKs. + - [RTL8195AM](https://www.realtek.com/en/products/communications-network-ics/item/rtl8195am) - RTL8710AF (found in amb1_arduino) - [RTL8711AM](https://www.realtek.com/en/products/communications-network-ics/item/rtl8711am) @@ -187,6 +189,7 @@ MQTT | ✅ SD | ❌ Symbols: + - ✔️ working - ✅ tested, external library - ❓ untested @@ -195,6 +198,7 @@ Symbols: - \- not applicable Names: + - Core functions - stuff like delay(), millis(), yield(), etc. - **CORE LIBRARIES** - included normally in all Arduino cores - **OTHER LIBRARIES** - included in ESP32 core or downloadable diff --git a/boards/wr3/README.md b/boards/wr3/README.md index cbbf685..885e5fb 100644 --- a/boards/wr3/README.md +++ b/boards/wr3/README.md @@ -2,7 +2,7 @@ [Product page](https://developer.tuya.com/en/docs/iot/wifiwr1module?id=K9605tc0k90t3) -- [Debugging](../../docs/platform/realtek/Debugging.md) +- [Debugging](../../docs/platform/realtek/debugging.md) Parameter | Value -------------|------------------------- diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 312e1e9..0000000 --- a/docs/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# LibreTuya documentation - -- [LibreTuya API](api/README.md) -- [Built-in libraries](libraries/README.md) -- [3-rd party libraries](Libraries.md) -- [Configuration options](API%20Configuration.md) - -## Realtek AmebaZ Series - -- [Debugging](platform/realtek/Debugging.md) -- [Exception decoder](platform/realtek/Exception%20decoder.md) diff --git a/docs/API Configuration.md b/docs/config.md similarity index 92% rename from docs/API Configuration.md rename to docs/config.md index ede2292..0a34675 100644 --- a/docs/API Configuration.md +++ b/docs/config.md @@ -1,6 +1,6 @@ # LibreTuya API Configuration -Note: see [LibreTuyaConfig.h](../../arduino/libretuya/api/LibreTuyaConfig.h) for most options and their defaults. +Note: see [LibreTuyaConfig.h](../arduino/libretuya/api/LibreTuyaConfig.h) for most options and their defaults. All options are configurable via C++ defines in PlatformIO project file. For example: ```ini diff --git a/docs/Libraries.md b/docs/libs-3rd-party.md similarity index 100% rename from docs/Libraries.md rename to docs/libs-3rd-party.md diff --git a/docs/libraries/README.md b/docs/libs-built-in.md similarity index 67% rename from docs/libraries/README.md rename to docs/libs-built-in.md index a8cc7af..f943ae1 100644 --- a/docs/libraries/README.md +++ b/docs/libs-built-in.md @@ -3,23 +3,23 @@ ## base64 - [Source](https://github.com/espressif/arduino-esp32/blob/master/cores/esp32/base64.cpp): ESP32 Arduino Core -- [API](../../arduino/libretuya/libraries/base64/base64.h) +- [API](../arduino/libretuya/libraries/base64/base64.h) 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) +- [API](../arduino/libretuya/libraries/HTTPClient/HTTPClient.h) - [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). ## WiFiMulti - [Source](https://github.com/espressif/arduino-esp32/tree/master/libraries/WiFi/src): ESP32 Arduino Core -- [API](../../arduino/libretuya/libraries/WiFiMulti/WiFiMulti.h) +- [API](../arduino/libretuya/libraries/WiFiMulti/WiFiMulti.h) - [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) - - [WiFiClientBasic](https://github.com/espressif/arduino-esp32/blob/master/libraries/WiFi/examples/WiFiClientBasic/WiFiClientBasic.ino) + - [WiFiMulti](https://github.com/espressif/arduino-esp32/blob/master/libraries/WiFi/examples/WiFiMulti/WiFiMulti.ino) + - [WiFiClientBasic](https://github.com/espressif/arduino-esp32/blob/master/libraries/WiFi/examples/WiFiClientBasic/WiFiClientBasic.ino) Class for selecting best available AP from a list of several ones. diff --git a/docs/platform/realtek/Exception decoder.md b/docs/platform/realtek/exception-decoder.md similarity index 100% rename from docs/platform/realtek/Exception decoder.md rename to docs/platform/realtek/exception-decoder.md diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..fbee236 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +mkdocs-same-dir diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..caf99cb --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,23 @@ +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 +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" + - "Debugging": "docs/platform/realtek/debugging.md" + - "Exception decoder": "docs/platform/realtek/exception-decoder.md"