Feature/toolkit documentation

.github/workflows/build-deploy-ghpages.yml

@@ -0,0 +1,62 @@
+name: Build Documentation and Deploy
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+  pages: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      # Checkout the repository
+      - name: Checkout repository
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+          submodules: "true"
+          ref: "feature/toolkit-documentation"
+
+      - name: Set Version
+        run: echo "PROJECT_NUMBER = `git describe --tags`" >> ./docs/doxygen/doxygen-config
+
+      - name: Build Documentation
+        uses: mattnotmitt/doxygen-action@v1.9.5
+        with:
+          doxyfile-path: "./docs/doxygen/doxygen-config"
+
+      # Upload the documentation as an artifact
+      - name: Upload documentation
+        uses: actions/upload-pages-artifact@v3.0.1
+        with:
+          path: ./docs/html
+
+  # Deploy job
+  deploy:
+    # Add a dependency to the build job
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    # Specify runner + deployment step
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4 # or specific "vX.X.X" version tag for this action

.gitignore

@@ -1,3 +1,5 @@
 # VSCode directories
 .vscode
 
+
+docs/html/

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "docs/doxygen/doxygen-awesome-css"]
+	path = docs/doxygen/doxygen-awesome-css
+	url = https://github.com/jothepro/doxygen-awesome-css.git

README.md

@@ -5,25 +5,38 @@
 ![GitHub release (with filter)](https://img.shields.io/github/v/release/sparkfun/SparkFun_Toolkit)
 ![GitHub (Pre-)Release Date](https://img.shields.io/github/release-date-pre/sparkfun/SparkFun_Toolkit)
 
+The SparkFun Toolkit provides a common set of core functionality for use across the SparkFun Arduino Driver library. Instead of each device driver library implementing it's own communication layers, error types and design, the SparkFun Toolkit library is used.
 
+## Motivation
 
-The SparkFun Toolkit provides a common set of core functionality for use across the SparkFun Arduino Driver library. Instead of each device driver library implementing it's own communication layers, error types and design, the SparkFun Toolkit library is used.
+Often, the same core functionality is implemented with a majority of our Arduino libraries, each implementation providing the same functionality, but implemented differently. The result is solutions that have different quirks, and impossible to maintain/support effectively. The SparkFun Toolkit solves this issue.
 
-By using the SparkFun Toolkit, Arduino drivers achieve the following benefits:
+The SparkFun Toolkit provides a single implementation of common functionality used in the software developed for SparkFun boards. Initially targeted  at the Arduino development environment, the SparkFun Toolkit delivers the following benefits:
 
 * Use a well-tested and validated implementation
 * Reduce development effort
 * Implement functionality following a common structure
 * Set the foundation for future enhancements - as the capabilities of the toolkit grow, these features become available with little to any implementation effort.
 
-## Current Status
+## Documentation
+
+The SparkFun Toolkit Development documentation is available [here](https://docs.sparkfun.com/SparkFun_Toolkit)
+
+## Installation and Use
+
+To use the SparkFun Toolkit directly, or in library development kit is installable via the Arduino Library Manager - search for `SparkFun ToolKit` within the Arduino Library Manager to install.
+
+However, for solutions that use the SparkFun Toolkit, it is installed automatically during the Arduino library installation process, by marking the Toolkit as a dependency when publishing your library.
+
+To mark the `SparkFun Toolkit` as a dependency, add the following line to the `library.properties` file for your library.
 
-### December 2023
+```INI
+depends=SparkFun Toolkit
+```
 
-The SparkFun Toolkit is available as a *Beta* release, with the intent of testing and validation by SparkFun. The community are free to use this toolkit with the understanding that interfaces, types and class structures could change.
+## Examples
 
-### Documentation
+The following Arduino Libraries are making use of the SparkFun Toolkit:
 
-|||
-|---|---|
-|[Bus Implementation](docs/ar_ibus.md) | The architecture and use of the Toolkit Communication Bus Interface
+* [SparkFun Qwiic Pulsed Coherent Radar Sensor XM125](https://github.com/sparkfun/SparkFun_Qwiic_XM125_Arduino_Library)
+* [SparkFun Qwiic AS7331 Spectral UV Sensor](https://github.com/sparkfun/SparkFun_AS7331_Arduino_Library)

docs/ar_ibus.md

@@ -1,10 +1,10 @@
-# Overview - Device Bus Interface - sfeTkIBus
+# Device Bus Interface - Overview
 
 One of the foundational capabilities of the SparkFun Toolkit is bus communication with devices. This is a common task almost all libraries implement using their own implementation for I2C, SPI or UART bus communication.
 
 For bus communication, the SparkFun Toolkit is designed to provide a common implementation for use across all SparkFun libraries. Additionally, the bus architecture is modeled on a *driver* pattern, separating  the individual bus setup/configuration from data communication, enabling a single device implementation to easily support a variety of device bus types.
 
-### The Bus Interface Design Pattern
+## The Bus Interface Design Pattern
 
 This pattern allows an application to develop against the common bus interface without regard to the underlying bus type or implementation. This *plug-in* nature of this model enables core application reuse across a range of bus devices. What to use a different bus type? Just use a different driver.
 
@@ -35,9 +35,9 @@ The key class to support this pattern are:
 
 | | |
 |------|-------|
-**sfeTkIBus** | A virtual C++ class that device the bus ```sfeTkIBus``` interface |
-**sfeTkII2C** | Sub-class of the ```sfeTkIIBus``` interface, it provides an interface for I2C devices|
-**sfeTkISPI** | Sub-class of the ```sfeTkIIBus``` interface, it provides an interface for SPI devices |
+|**sfeTkIBus** | A virtual C++ class that device the bus ```sfeTkIBus``` interface |
+|**sfeTkII2C** | Sub-class of the ```sfeTkIIBus``` interface, it provides an interface for I2C devices|
+|**sfeTkISPI** | Sub-class of the ```sfeTkIIBus``` interface, it provides an interface for SPI devices |
 
 ### The sfeTkIBus Interface
 
@@ -47,12 +47,12 @@ The interface methods:
 
 | Method| Definition |
 |------|-------|
-**writeRegisterByte** | Write a byte of data to a particular register of a device |
-**writeRegisterWord** | Write a word of data to a particular register of a device |
-**writeRegisterRegion** | Write an array of data to a particular register of a device|
-**readRegisterByte** | Read a byte of data from a particular register of a device |
-**readRegisterWord** | Read a word of data from a particular register of a device |
-**readRegisterRegion** | Read an array of data from a particular register of a device |
+|**writeRegisterByte** | Write a byte of data to a particular register of a device |
+|**writeRegisterWord** | Write a word of data to a particular register of a device |
+|**writeRegisterRegion** | Write an array of data to a particular register of a device|
+|**readRegisterByte** | Read a byte of data from a particular register of a device |
+|**readRegisterWord** | Read a word of data from a particular register of a device |
+|**readRegisterRegion** | Read an array of data from a particular register of a device |
 
 > [!NOTE]
 > This interface only defines the methods to read and write data on the given bus. Any address, or bus specific settings is provided/implemented by the implementation/specialization of this interface.
@@ -67,9 +67,9 @@ This class sub-classes from the ```sfeTkIBus``` interface adding additional func
 
 | Method| Definition |
 |------|-------|
-**ping** | Determine if a devices is connected to the I2C device at the address set on this bus object. This is an interface method |
-**setAddress** | Set the I2C address to use for this I2C object |
-**address** | Returns the address used by this I2C object |
+|**ping** | Determine if a devices is connected to the I2C device at the address set on this bus object. This is an interface method |
+|**setAddress** | Set the I2C address to use for this I2C object |
+|**address** | Returns the address used by this I2C object |
 
 > [!NOTE]
 > The ```sfeTkII2C``` class manages the device address for the I2C bus. As such, each I2C device instantiates/uses an instance of the ```sfeTkII2C``` class.
@@ -84,8 +84,8 @@ This class sub-classes from the ```sfeTkIBus``` interface adding additional func
 
 | Method| Definition |
 |------|-------|
-**setCS** | Set the CS Pin to use for this SPI object |
-**cs** | Returns the CS Pin used by this SPI object |
+|**setCS** | Set the CS Pin to use for this SPI object |
+|**cs** | Returns the CS Pin used by this SPI object |
 
 > [!NOTE]
 > The ```sfeTkISPI``` class manages CS Pin for the SPI bus. As such, each SPI device instantiates/uses an instance of the ```sfeTkISPI``` class.