Merge branch 'develop' of https://github.com/MaJerle/lwesp into develop

.vscode/tasks.json

@@ -42,5 +42,32 @@
             "args": [],
             "problemMatcher": [],
         },
+        {
+            "label": "Docs: Install python plugins from requirements.txt file",
+            "type": "shell",
+            "command": "python -m pip install -r requirements.txt",
+            "options": {
+                "cwd": "${workspaceFolder}/docs"
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Docs: Generate html",
+            "type": "shell",
+            "command": ".\\make html",
+            "options": {
+                "cwd": "${workspaceFolder}/docs"
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Docs: Clean build directory",
+            "type": "shell",
+            "command": ".\\make clean",
+            "options": {
+                "cwd": "${workspaceFolder}/docs"
+            },
+            "problemMatcher": []
+        },
     ]
 }

docs/api-reference/cli/cli_opt.rst

@@ -3,4 +3,5 @@
 CLI Configuration
 =================
 
-.. doxygengroup:: CLI_CONFIG
+.. doxygengroup:: CLI_CONFIG
+	:inner:

docs/api-reference/lwesp/conn.rst

@@ -35,7 +35,7 @@ Sending data
 ^^^^^^^^^^^^
 
 Receiving data flow is always the same. Whenever new data packet arrives, corresponding event is called to notify application layer.
-When it comes to sending data, application may decide between ``2`` options (*this is valid only for non-UDP connections):
+When it comes to sending data, application may decide between ``2`` options (*this is valid only for non-UDP connections*):
 
 * Write data to temporary transmit buffer
 * Execute *send command* for every API function call

docs/api-reference/opt.rst

@@ -10,11 +10,4 @@ When any of the settings shall be modified, it shall be done in dedicated applic
 	Check :ref:`getting_started` for guidelines on how to create and use configuration file.
 
 .. doxygengroup:: LWESP_OPT
-.. doxygengroup:: LWESP_OPT_DBG
-.. doxygengroup:: LWESP_OPT_OS
-.. doxygengroup:: LWESP_OPT_STD_LIB
-.. doxygengroup:: LWESP_OPT_MODULES
-.. doxygengroup:: LWESP_OPT_MODULES_NETCONN
-.. doxygengroup:: LWESP_OPT_MODULES_MQTT
-.. doxygengroup:: LWESP_OPT_MODULES_CAYENNE
-.. doxygengroup:: LWESP_OPT_APP_HTTP
+	:inner:

docs/conf.py

@@ -23,15 +23,25 @@
 # -- Project information -----------------------------------------------------
 
 project = 'LwESP'
-copyright = '2020, Tilen MAJERLE'
+copyright = '2022, Tilen MAJERLE'
 author = 'Tilen MAJERLE'
 
 # Try to get branch at which this is running
 # and try to determine which version to display in sphinx
-# Version is using git tag if on master or "latest-develop" if on develop branch
+# Version is using git tag if on master/main or "latest-develop" if on develop branch
 version = ''
 git_branch = ''
 
+def cmd_exec_print(t):
+    print("cmd > ", t, "\n", os.popen(t).read().strip(), "\n")
+
+# Print demo data here
+cmd_exec_print('git branch')
+cmd_exec_print('git describe')
+cmd_exec_print('git describe --tags')
+cmd_exec_print('git describe --tags --abbrev=0')
+cmd_exec_print('git describe --tags --abbrev=1')
+
 # Get current branch
 res = os.popen('git branch').read().strip()
 for line in res.split("\n"):
@@ -41,17 +51,18 @@
 # Decision for display version
 git_branch = git_branch.replace('(HEAD detached at ', '').replace(')', '')
 if git_branch.find('master') >= 0 or git_branch.find('main') >= 0:
-    version = os.popen('git describe --tags --abbrev=0').read().strip()
-    if version == '':
-        version = 'v0.0.0'
-elif git_branch.find('develop') != -1 and not (git_branch.find('develop-') >= 0 or git_branch.find('develop/') >= 0):
+    #version = os.popen('git describe --tags --abbrev=0').read().strip()
+    version = 'latest-stable'
+elif git_branch.find('develop-') >= 0 or git_branch.find('develop/') >= 0:
+    version = 'branch-' + git_branch
+elif git_branch == 'develop' or git_branch == 'origin/develop':
     version = 'latest-develop'
 else:
-    version = 'branch-' + git_branch
+    version = os.popen('git describe --tags --abbrev=0').read().strip()
 
 # For debugging purpose only
 print("GIT BRANCH: " + git_branch)
-print("GIT VERSION: " + version)
+print("PROJ VERSION: " + version)
 
 # -- General configuration ---------------------------------------------------
 
@@ -115,20 +126,19 @@
 html_css_files = [
     'css/common.css',
     'css/custom.css',
+    'https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.1/css/all.min.css',
 ]
 html_js_files = [
-    'https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.1/css/all.min.css'
+    ''
 ]
 
+# Master index file
 master_doc = 'index'
 
-#
-# Breathe configuration
-#
-#
-#
+# --- Breathe configuration -----------------------------------------------------
 breathe_projects = {
-	"esp_at_lib": "_build/xml/"
+	"lwesp": "_build/xml/"
 }
-breathe_default_project = "esp_at_lib"
-breathe_default_members = ('members', 'undoc-members')
+breathe_default_project = "lwesp"
+breathe_default_members = ('members', 'undoc-members')
+breathe_show_enumvalue_initializer = True

docs/examples/index.rst

@@ -6,10 +6,10 @@ Examples and demos
 Various examples are provided for fast library evaluation on embedded systems. These are prepared and maintained for ``2`` platforms, but could be easily extended to more platforms:
 
 * WIN32 examples, prepared as `Visual Studio Community <https://visualstudio.microsoft.com/vs/community/>`_ projects
-* ARM Cortex-M examples for STM32, prepared as `STM32CubeIDE <https://www.st.com/en/development-tools/stm32cubeide.html>`_ GCC projects
+* ARM Cortex-M examples for STM32, prepared as `STM32CubeIDE <https://www.st.com/en/development-tools/stm32cubeide.html>`_ GCC projects. These are also supported in *Visual Studio Code* through *CMake* and *ninja* build system. `Dedicated tutorial <https://github.com/MaJerle/stm32-cube-cmake-vscode>`_ is available to get started in *VSCode*.
 
-.. warning::
-	Library is platform independent and can be used on any platform.
+.. note::
+	Library is platform agnostic and can be used on many different products
 
 Example architectures
 ^^^^^^^^^^^^^^^^^^^^^
@@ -92,58 +92,58 @@ Here is a list of all examples coming with this library.
 	Application needs to modify file ``/snippets/station_manager.c`` and update ``ap_list`` variable with preferred access points,
 	in order to allow *ESP* to connect to home/local network
 
-Ex. Access point
-****************
+Access point
+************
 
 *ESP* device is configured as software access point, allowing stations to connect to it.
 When station connects to access point, it will output its *MAC* and *IP* addresses.
 
-Ex. Client
-**********
+Client
+******
 
 Application tries to connect to custom server with classic, event-based API.
 It starts concurrent connections and processes data in its event callback function.
 
-Ex. Server
-**********
+Server
+******
 
 It starts server on port ``80`` in event based connection mode.
 Every client is processed in callback function.
 
 When *ESP* is successfully connected to access point, it is possible to connect to it using its assigned IP address.
 
-Ex. Domain name server
-**********************
+Domain name server
+******************
 
 *ESP* tries to get domain name from specific domain name, ``example.com`` as an example.
 It needs to be connected to access point to have access to global internet.
 
-Ex. MQTT Client
-***************
+MQTT Client
+***********
 
 This example demonstrates raw MQTT connection to mosquitto test server.
 A new application thread is started after *ESP* successfully connects to access point.
 MQTT application starts by initiating a new TCP connection.
 
 This is event-based example as there is no linear code.
 
-Ex. MQTT Client API
-*******************
+MQTT Client API
+***************
 
 Similar to *MQTT Client* examples, but it uses separate thread to process
 events in blocking mode. Application does not use events to process data,
 rather it uses blocking API to receive packets
 
-Ex. Netconn client
-******************
+Netconn client
+**************
 
 Netconn client is based on sequential API.
 It starts connection to server, sends initial request and then waits to receive data.
 
 Processing is in separate thread and fully sequential, no callbacks or events.
 
-Ex. Netconn server
-******************
+Netconn server
+**************
 
 Netconn server is based on sequential API.
 It starts server on specific port (see example details) and it waits for new client in separate threads.

docs/get-started/index.rst

@@ -13,10 +13,10 @@ Download library
 
 Library is primarly hosted on `Github <https://github.com/MaJerle/lwesp>`_.
 
-You can get it with:
+You can get it by:
 
 * Downloading latest release from `releases area <https://github.com/MaJerle/lwesp/releases>`_ on Github
-* Clone ``master`` branch for latest stable version
+* Clone ``main`` branch for latest stable version
 * Clone ``develop`` branch for latest development
 
 Download from releases
@@ -34,19 +34,19 @@ This is used when you do not have yet local copy on your machine.
 
 * Make sure ``git`` is installed.
 * Open console and navigate to path in the system to clone repository to. Use command ``cd your_path``
-* Clone repository with one of available ``3`` options
+* Clone repository with one of available options below
 
   * Run ``git clone --recurse-submodules https://github.com/MaJerle/lwesp`` command to clone entire repository, including submodules
   * Run ``git clone --recurse-submodules --branch develop https://github.com/MaJerle/lwesp`` to clone `development` branch, including submodules
-  * Run ``git clone --recurse-submodules --branch master https://github.com/MaJerle/lwesp`` to clone `latest stable` branch, including submodules
+  * Run ``git clone --recurse-submodules --branch main https://github.com/MaJerle/lwesp`` to clone `latest stable` branch, including submodules
 
 * Navigate to ``examples`` directory and run favourite example
 
 Update cloned to latest version
 """""""""""""""""""""""""""""""
 
 * Open console and navigate to path in the system where your repository is located. Use command ``cd your_path``
-* Run ``git pull origin master`` command to get latest changes on ``master`` branch
+* Run ``git pull origin main`` command to get latest changes on ``main`` branch
 * Run ``git pull origin develop`` command to get latest changes on ``develop`` branch
 * Run ``git submodule update --init --remote`` to update submodules to latest version
 

docs/index.rst

@@ -72,10 +72,29 @@ Table of contents
 
 .. toctree::
     :maxdepth: 2
+    :caption: Contents
 
     self
     get-started/index
     user-manual/index
     api-reference/index
     examples/index
     firmware-update/index
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Other projects
+    :hidden:
+
+    LwDTC - DateTimeCron <https://github.com/MaJerle/lwdtc>
+    LwESP - ESP-AT library <https://github.com/MaJerle/lwesp>
+    LwGPS - GPS NMEA parser <https://github.com/MaJerle/lwgps>
+    LwGSM - GSM-AT library <https://github.com/MaJerle/lwgsm>
+    LwJSON - JSON parser <https://github.com/MaJerle/lwjson>
+    LwMEM - Memory manager <https://github.com/MaJerle/lwmem>
+    LwOW - OneWire with UART <https://github.com/MaJerle/lwow>
+    LwPKT - Packet protocol <https://github.com/MaJerle/lwpkt>
+    LwPRINTF - Printf <https://github.com/MaJerle/lwprintf>
+    LwRB - Ring buffer <https://github.com/MaJerle/lwrb>
+    LwSHELL - Shell <https://github.com/MaJerle/lwshell>
+    LwUTIL - Utility functions <https://github.com/MaJerle/lwutil>

docs/requirements.txt

@@ -1,8 +1,12 @@
-breathe>=4.9.1
+# Used to generate docs
+
+breathe>=4.30,<4.33
 colorama
 docutils==0.16
-sphinx>=3.5.1
-sphinx_rtd_theme
+sphinx~=4.0
+sphinx_rtd_theme~=1.0
+sphinx-notfound-page
 sphinx-tabs
 sphinxcontrib-svg2pdfconverter
 sphinx-sitemap
+pygments>=2.9