docs: README as main page, more links

The landing page of the doxygen docs is now identical
to README.md from GitHub.

Including links to external Golioth cloud documentation
from golioth.io.

Doxygen formatting tweaks for better UI and navigation.

Signed-off-by: Nick Miller <[email protected]>

.gitignore

@@ -4,3 +4,4 @@ sdkconfig.old
 build.tar.gz
 credentials.yml
 .vscode
+firebase-debug.log

README.md

@@ -7,7 +7,49 @@ This repo contains a runtime library and set of examples intended to build
 and run in the latest release of esp-idf
 (currently [4.4.1](https://github.com/espressif/esp-idf/releases/tag/v4.4.1)).
 
-## Cloning this repo
+SDK source: https://github.com/golioth/golioth-esp-idf-sdk
+
+API documentation: https://esp-idf-sdk-docs.golioth.io/
+
+## Getting Started
+
+### Hello, Golioth!
+
+Here is a minimal example that demonstrates how to connect to
+[Golioth cloud](https://docs.golioth.io/cloud) and send the message "Hello, Golioth!":
+
+```c
+#include "wifi.h"
+#include "golioth.h"
+
+void app_main(void) {
+    const char* wifi_ssid = "SSID";
+    const char* wifi_password = "Password";
+    const char* golioth_psk_id = "device@project";
+    const char* golioth_psk = "supersecret";
+
+    wifi_init(wifi_ssid, wifi_password);
+    wifi_wait_for_connected();
+
+    golioth_client_config_t config = {
+        .credentials = {
+            .auth_type = GOLIOTH_TLS_AUTH_TYPE_PSK,
+            .psk = {
+                    .psk_id = golioth_psk_id,
+                    .psk_id_len = strlen(golioth_psk_id),
+                    .psk = golioth_psk,
+                    .psk_len = strlen(golioth_psk),
+            }
+        }
+    };
+
+    golioth_client_t client = golioth_client_create(&config);
+    golioth_log_info_sync(client, "app_main", "Hello, Golioth!", 5.0);
+}
+
+```
+
+### Cloning this repo
 
 This repo uses git submodules, so you will need to clone with the `--recursive` option:
 
@@ -23,7 +65,7 @@ cd golioth-esp-idf-sdk
 git submodule update --init --recursive
 ```
 
-## Install esp-idf
+### Install esp-idf
 
 Install version 4.4.1 of esp-idf using the
 [installation directions from Espressif](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html#installation).
@@ -42,12 +84,16 @@ git submodule update --init --recursive
 ./install.sh all
 ```
 
-## Trying the Golioth SDK examples
+### Trying the SDK examples
 
 The `examples` directory contains example apps which you can build and run.
 
 The `golioth_basics` example is recommended as a starting point, to learn how to
-connect to Golioth and use services like LightDB state, LightDB stream, Logging, and OTA.
+connect to Golioth and use services like
+[LightDB state](https://docs.golioth.io/cloud/services/lightdb),
+[LightDB stream](https://docs.golioth.io/cloud/services/lightdb-stream),
+[Logging](https://docs.golioth.io/cloud/services/logging),
+and [OTA](https://docs.golioth.io/cloud/services/ota).
 
 ### Using VSCode esp-idf extension
 
@@ -71,7 +117,7 @@ idf.py flash
 idf.py monitor
 ```
 
-## Integrating the Golioth SDK
+## Integrating the SDK
 
 The recommended way to integrate this SDK into an external application is to add it as a
 git submodule. For example:
@@ -112,7 +158,7 @@ A complete example of using the Golioth SDK in an external project can be found
 
 https://github.com/golioth/golioth-esp-idf-external-app.git
 
-## Device Matrix
+## Verified Devices
 
 The following table lists the different hardware configurations we test the SDK against,
 and when it was last tested.

components/golioth_sdk/include/golioth_client.h

@@ -11,6 +11,17 @@
 
 /// @defgroup golioth_client golioth_client
 /// Functions for creating a Golioth client and managing client lifetime.
+///
+/// Used to connect to Golioth cloud using the CoAP protocol over DTLS.
+///
+/// For authentication, you can use either pre-shared key (PSK) or
+/// X.509 certificates (aka Public Key Infrastructure, PKI).
+///
+/// https://docs.golioth.io/reference/protocols/coap
+/// <br>
+/// https://docs.golioth.io/reference/protocols/coap/auth
+/// <br>
+/// https://docs.golioth.io/reference/protocols/device-auth
 /// @{
 
 /// @brief Opaque handle to the Golioth client

components/golioth_sdk/include/golioth_fw_update.h

@@ -9,6 +9,8 @@
 
 /// @defgroup golioth_fw_update golioth_fw_update
 /// Create a background task that will execute Over-the-Air (OTA) updates
+///
+/// https://docs.golioth.io/reference/protocols/coap/ota
 /// @{
 
 /// Create a task that will perform firmware updates.

components/golioth_sdk/include/golioth_lightdb.h

@@ -10,6 +10,10 @@
 
 /// @defgroup golioth_lightdb golioth_lightdb
 /// Functions for interacting with Golioth LightDB state and LightDB stream services.
+///
+/// https://docs.golioth.io/reference/protocols/coap/lightdb
+/// <br>
+/// https://docs.golioth.io/reference/protocols/coap/lightdb-stream
 /// @{
 
 /// Convert raw byte payload into an int32_t

components/golioth_sdk/include/golioth_log.h

@@ -10,6 +10,8 @@
 
 /// @defgroup golioth_log golioth_log
 /// Functions for logging messages to Golioth
+///
+/// https://docs.golioth.io/reference/protocols/coap/logging
 /// @{
 
 /// Log an error to Golioth asynchronously

components/golioth_sdk/include/golioth_ota.h

@@ -11,6 +11,8 @@
 
 /// @defgroup golioth_ota golioth_ota
 /// Functions for interacting with Golioth OTA services
+///
+/// https://docs.golioth.io/reference/protocols/coap/ota
 /// @{
 
 /// Maximum size of an OTA block, in bytes

docs/README.md

@@ -37,14 +37,12 @@ Install Firebase following the official [Firebase docs](https://firebase.google.
 Serve locally, for testing:
 
 ```sh
-cd firebase
 firebase serve --only hosting
 ```
 
 Deploy to Firebase `golioth-esp-idf-sdk-doxygen-dev`:
 
 ```sh
-cd firebase
 firebase login
 firebase deploy --only docs-dev
 ```

docs/doxygen/Doxyfile

@@ -158,7 +158,7 @@ INLINE_INHERITED_MEMB  = NO
 # shortest path that makes the file name unique will be used
 # The default value is: YES.
 
-FULL_PATH_NAMES        = YES
+FULL_PATH_NAMES        = NO
 
 # The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path.
 # Stripping is only done if one of the specified strings matches the left-hand
@@ -277,7 +277,7 @@ ALIASES                =
 # members will be omitted, etc.
 # The default value is: NO.
 
-OPTIMIZE_OUTPUT_FOR_C  = NO
+OPTIMIZE_OUTPUT_FOR_C  = YES
 
 # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or
 # Python sources only. Doxygen will then generate output that is more tailored
@@ -509,7 +509,7 @@ EXTRACT_PACKAGE        = NO
 # included in the documentation.
 # The default value is: NO.
 
-EXTRACT_STATIC         = NO
+EXTRACT_STATIC         = YES
 
 # If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined
 # locally in source files will be included in the documentation. If set to NO,
@@ -594,7 +594,7 @@ INTERNAL_DOCS          = NO
 # YES.
 # The default value is: system dependent.
 
-CASE_SENSE_NAMES       = NO
+CASE_SENSE_NAMES       = YES
 
 # If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with
 # their full class and namespace scopes in the documentation. If set to YES, the
@@ -667,7 +667,7 @@ SORT_MEMBERS_CTORS_1ST = NO
 # appear in their defined order.
 # The default value is: NO.
 
-SORT_GROUP_NAMES       = NO
+SORT_GROUP_NAMES       = YES
 
 # If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by
 # fully-qualified names, including namespaces. If set to NO, the class list will
@@ -705,7 +705,7 @@ GENERATE_TESTLIST      = YES
 # list. This list is created by putting \bug commands in the documentation.
 # The default value is: YES.
 
-GENERATE_BUGLIST       = YES
+GENERATE_BUGLIST       = NO
 
 # The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO)
 # the deprecated list. This list is created by putting \deprecated commands in
@@ -836,7 +836,7 @@ WARN_NO_PARAMDOC       = NO
 # Possible values are: NO, YES and FAIL_ON_WARNINGS.
 # The default value is: NO.
 
-WARN_AS_ERROR          = NO
+WARN_AS_ERROR          = YES
 
 # The WARN_FORMAT tag determines the format of the warning messages that doxygen
 # can produce. The string should contain the $file, $line, and $text tags, which
@@ -864,7 +864,8 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = "../../components/golioth_sdk/include"
+INPUT                  = "../../components/golioth_sdk/include" \
+                         "../../README.md"
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1061,7 +1062,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE =
+USE_MDFILE_AS_MAINPAGE = "../../README.md"
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing
@@ -1074,7 +1075,7 @@ USE_MDFILE_AS_MAINPAGE =
 # also VERBATIM_HEADERS is set to NO.
 # The default value is: NO.
 
-SOURCE_BROWSER         = NO
+SOURCE_BROWSER         = YES
 
 # Setting the INLINE_SOURCES tag to YES will include the body of functions,
 # classes and enums directly into the documentation.
@@ -1196,7 +1197,7 @@ CLANG_DATABASE_PATH    =
 # classes, structs, unions or interfaces.
 # The default value is: YES.
 
-ALPHABETICAL_INDEX     = YES
+ALPHABETICAL_INDEX     = NO
 
 # In case all classes in a project start with a common prefix, all classes will
 # be put under the same header in the alphabetical index. The IGNORE_PREFIX tag
@@ -1332,7 +1333,7 @@ HTML_COLORSTYLE_GAMMA  = 80
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_TIMESTAMP         = NO
+HTML_TIMESTAMP         = YES
 
 # If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML
 # documentation will contain a main index with vertical navigation menus that
@@ -1351,7 +1352,7 @@ HTML_DYNAMIC_MENUS     = YES
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_DYNAMIC_SECTIONS  = NO
+HTML_DYNAMIC_SECTIONS  = YES
 
 # With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries
 # shown in the various tree structured indices initially; the user can expand
@@ -1565,7 +1566,7 @@ ECLIPSE_DOC_ID         = org.doxygen.Project
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-DISABLE_INDEX          = YES
+DISABLE_INDEX          = NO
 
 # The GENERATE_TREEVIEW tag is used to specify whether a tree-like index
 # structure should be generated to display hierarchical information. If the tag