[Draft] Added Docs site (#150)

.github/workflows/builds-docs.yml

@@ -0,0 +1,24 @@
+name: github pages
+
+on:
+  push:
+    branches:
+      - dev
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: docfx-action
+        uses: nikeee/[email protected]
+        with:
+          args: docs/docfx.json
+
+      - name: Deploy
+        uses: peaceiris/[email protected]
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/_site

README.md

@@ -1,6 +1,7 @@
 # StreamDeckToolkit
 
 [![Build status](https://dev.azure.com/FritzAndFriends/StreamDeckTools/_apis/build/status/StreamDeckTools-CI)](https://dev.azure.com/FritzAndFriends/StreamDeckTools/_build/latest?definitionId=8)  ![](https://vsrm.dev.azure.com/FritzAndFriends/_apis/public/Release/badge/00a6d40c-eb0d-4aa8-a405-d13d03317ca9/1/1)  [![NuGet](https://img.shields.io/nuget/v/StreamDeckLib.svg)](https://www.nuget.org/packages/StreamDeckLib/)
+[![github pages](https://github.com/FritzAndFriends/StreamDeckToolkit/workflows/github%20pages/badge.svg)](https://github.com/FritzAndFriends/StreamDeckToolkit/actions?query=workflow%3A%22github+pages%22)
 
 ![](https://img.shields.io/azure-devops/tests/FritzAndFriends/StreamDeckTools/8/dev.svg)
 
@@ -10,6 +11,10 @@
 
 This is a template to help create plugins for the [Elgato Stream Deck][Stream Deck], using the [Stream Deck SDK][] with [Dotnet Core][].
 
+## Docs
+
+You can read more in the [Docs](https://FritzAndFriends.github.io/StreamDeckToolkit/).
+
 ## Pre-Requisites
 
 In order to make use of this template, you will need to have the [Dotnet Core SDK][] (version 2.2.100 or above) installed on your development machine.

docs/.gitignore

@@ -0,0 +1,9 @@
+###############
+#    folder   #
+###############
+/**/DROP/
+/**/TEMP/
+/**/packages/
+/**/bin/
+/**/obj/
+_site

docs/api/.gitignore

@@ -0,0 +1,5 @@
+###############
+#  temp file  #
+###############
+*.yml
+.manifest

docs/api/index.md

@@ -0,0 +1,3 @@
+# API Documentaion
+
+Welcome to the API Documentation, please see the navigation for each of the project apis in "StreamDeck Toolkit".

docs/articles/contributing.md

@@ -0,0 +1,45 @@
+## Contributing
+
+There are two ways to contribute to this repo, either the code or the docs.
+
+First check for any open [Issues](https://github.com/FritzAndFriends/StreamDeckToolkit/issues) on [GitHub](https://github.com/FritzAndFriends/StreamDeckToolkit) then comment to indicate you're helping out, or raise a new one with details.
+
+### Code
+
+Pull the code and add your necessary changes, then PR back to dev for review.
+
+### Docs
+
+You're in them! To help out fork this repo, install [DocFX](https://dotnet.github.io/docfx/) and update/add any info.
+
+`docfx docfx.json` will build the site, then move to the "_site" folder and run `docfx serve` then open a browser to "http://localhost:8080/" to see your updates.
+
+There are the Articles you can write to explain the toolkit, then the API docs which builds from the src.
+
+The [docfx.json](../docfx.json) file contains a `metadata` which points to the `src` to built to produce
+
+    {
+        "metadata": [
+        {
+            "src": [
+                {
+                    "files": ["**.csproj"],
+                    "src": "../src"
+                }
+            ],
+            "dest": "api"
+        }
+        ]
+    }
+
+### Template
+
+This documentation site is using the [DocFX Material](https://ovasquez.github.io/docfx-material/) [template](https://dotnet.github.io/docfx/templates-and-plugins/templates-dashboard.html).
+
+The [docfx.json](../docfx.json) file contains a `template` that has been updated, alongside the [templates](../tempaltes) folder containing the src of the template.
+
+    "template": [
+        "default",
+        "templates/material"
+    ]
+

docs/articles/create.md

@@ -0,0 +1,11 @@
+## Creating a Plugin Action
+
+The Stream Deck Toolkit provides the functionality that communicates directly with the Stream Deck software. When creating a plugin, you are responsible for creating actions for the Stream Deck buttons to perform. There are two base classes that you can inherit from when creating your action:
+
+1. `BaseStreamDeckAction` - this class contains all the integrations necessary to communicate with the Stream Deck at the 'barebones' level. Inheriting from this class will give you the greatest control over how your action sends and receives data from the software.
+
+2. `BaseStreamDeckActionWithSettingsModel<T>` - this class inherits from BaseStreamDeckAction, this class will automate the population of model properties, where type T is defined as the data that is stored when issuing a 'setSettings' event to the Stream Deck software. The property **`SettingsModel`** will automatically instantiate an instance of class T, so it is best to assign default values when defining your class T. Also, when using the Property Inspector and passing data back and forth, ensure that the properties defined in the settingsModel in JavaScript matches those that you have defined in T for the automatic mapping to occur between both environments.
+
+Your project may contain any number of actions, inheriting from one of the classes above. In order for the Action to be automatically registered on start up, it must bear the **`[ActionUuid(Uuid="com.fritzanfriends.pluginname.anotheraction")]`** attribute.
+
+Actions must also be manually registered in the **`manifest.json`** file, with the Uuid that matches ActionUuid attribute.

docs/articles/install.md

@@ -0,0 +1,25 @@
+## Install Project Template
+
+### From File System
+
+Installing the template from your filesystem is useful for local testing of the template itself. If you are actively working on the template making changes, this is the route you need to use.
+
+To install, run the following command from the root of the repository.
+
+`dotnet new -i Templates/StreamDeck.PluginTemplate.Csharp`
+
+To pick up any changes you have made to the template source, you must uninstall the template and reinstall it.
+
+To uninstall, run the following command from the root of the respository.
+
+**Windows:**  `dotnet new -u Templates/StreamDeck.PluginTemplate.Csharp`
+
+**OSX/Linux:** `dotnet new -u $PWD/Templates/StreamDeck.PluginTemplate.Csharp`
+
+### From NuGet
+
+`dotnet new -i StreamDeckPluginTemplate`
+
+- OR -
+
+`Install-Package StreamDeckPluginTemplate [-Version x.y.zzz]`

docs/articles/intro.md

@@ -0,0 +1,13 @@
+## Welcome
+
+Welcome to the documentation for the StreamDeck Toolkit, a .NET Standard library, template, and tools for building extensions to the Elgato Stream Deck.
+
+## What Is This?
+
+This is a template to help create plugins for the [Elgato Stream Deck][Stream Deck], using the [Stream Deck SDK][] with [Dotnet Core][].
+
+<!-- Reference Links -->
+
+[Dotnet Core]: https://dotnet.microsoft.com/ "Free, cross-platform application framework"
+[Stream Deck]: https://www.elgato.com/gaming/stream-deck/ "Elgato's Stream Deck product page"
+[Stream Deck SDK]: https://developer.elgato.com/documentation/stream-deck "Elgato's Stream Deck SDK documentation and reference site"

docs/articles/plugins.md

@@ -0,0 +1,9 @@
+## Plugins
+
+Please add your plugins to the list:
+
+- [vscode-streamdeck](https://github.com/nicollasricas/vscode-streamdeck)
+- [streamdeck-plugins](https://github.com/madmatt/streamdeck-plugins)
+  - https://streamdeck-plugins.com/
+  - [WayBack Machine version](https://web.archive.org/web/20200424173307/https://streamdeck-plugins.com/)
+- [BarRaider](https://barraider.com/)

docs/articles/pre-reqs.md

@@ -0,0 +1,10 @@
+## Pre-Requisites
+
+In order to make use of this template, you will need to have the [Dotnet Core SDK][] (version 2.2.100 or above) installed on your development machine.
+
+While not absolutely necessary, it is **strongly** recommended to have the [Stream Deck Software][] installed, to be able to perform some integration testing of your plugin.
+
+<!-- Reference Links -->
+
+[Dotnet Core SDK]: https://get.dot.net/ "Download the Dotnet Core SDK or Runtime"
+[Stream Deck Software]: https://www.elgato.com/gaming/downloads "Download the Stream Deck desktop software"

docs/articles/projects/dashboard.md

@@ -0,0 +1,5 @@
+## StreamDeck Dashboard
+
+A collection of stream deck actions in a single plugin for developers
+
+- [code](https://github.com/FritzAndFriends/StreamDeckDashboard)

docs/articles/projects/emulator.md

@@ -0,0 +1,9 @@
+## Stream Deck Emulator
+
+A simple emulator for the Stream Deck Application to allow plugin developers to develop, test, and debug their plugins without requiring a physical [Stream Deck][] device.
+
+See the [code](https://github.com/FritzAndFriends/StreamDeckEmulator).
+
+<!-- Reference Links -->
+
+[Stream Deck]: https://www.elgato.com/gaming/stream-deck/ "Elgato's Stream Deck product page"

docs/articles/projects/toc.yml

@@ -0,0 +1,4 @@
+- name: StreamDeck Emulator
+  href: emulator.md
+- name: StreamDeck Dashboard
+  href: dashboard.md

docs/articles/streams.md

@@ -0,0 +1,5 @@
+## Streams
+
+You can find all the [Twitch](https://www.twitch.tv/csharpfritz) streams that built this toolkit on [YouTube](https://www.youtube.com/channel/UCfvJirlbRTN-bU9sMWMb_ZQ)
+
+- [StreamDeck Toolkit Playlist](https://www.youtube.com/playlist?list=PLVMqA0_8O85xhVTS3OkTOKhe6IIYj7Tna)

docs/articles/template/action.md

@@ -0,0 +1,76 @@
+## Action
+
+When you use the template there are a number of parameters which can set things in the following `Action` class:
+
+    --uuid com.yourcompany.pluginname.actionname
+    --plugin-name FirstPlugin
+
+You will also have a model created `CounterSettingsModel` which will be set.
+
+### Attribute
+
+    [ActionUuid(Uuid="com.yourcompany.pluginname.actionname")]
+
+### Class Name
+
+The `--plugin-name` will be a prefix for the `Action` class that is created:
+
+    public class FirstPluginAction : BaseStreamDeckActionWithSettingsModel<Models.CounterSettingsModel>
+
+## BaseStreamDeckAction
+
+```csharp
+public ILogger Logger { get; }
+public string ActionUuid { get; }
+protected internal ConnectionManager Manager { get; set; }
+```
+
+There are a number of methods you can then override and implement with your own logic: 
+
+```csharp
+public virtual Task OnApplicationDidLaunch(StreamDeckEventPayload args);
+public virtual Task OnApplicationDidTerminate(StreamDeckEventPayload args);
+public virtual Task OnDeviceDidConnect(StreamDeckEventPayload args);
+public virtual Task OnDeviceDidDisconnect(StreamDeckEventPayload args);
+public virtual Task OnDidReceiveGlobalSettings(StreamDeckEventPayload args);
+public virtual Task OnDidReceiveSettings(StreamDeckEventPayload args);
+public virtual Task OnKeyDown(StreamDeckEventPayload args);
+public virtual Task OnKeyUp(StreamDeckEventPayload args);
+public virtual Task OnPropertyInspectorDidAppear(StreamDeckEventPayload args);
+public virtual Task OnPropertyInspectorDidDisappear(StreamDeckEventPayload args);
+public virtual Task OnTitleParametersDidChange(StreamDeckEventPayload args);
+public virtual Task OnWillAppear(StreamDeckEventPayload args);
+public virtual Task OnWillDisappear(StreamDeckEventPayload args);
+```
+
+Just call the base method then implement the functionality you wish to achieve.
+
+For example:
+
+```csharp
+public override async Task OnDidReceiveSettings(StreamDeckEventPayload args)
+{
+    await base.OnDidReceiveSettings(args);
+    await Manager.SetTitleAsync(args.context, SettingsModel.Counter.ToString());
+}
+```
+
+```csharp
+public override async Task OnWillAppear(StreamDeckEventPayload args)
+{
+    await base.OnWillAppear(args);
+    await Manager.SetTitleAsync(args.context, SettingsModel.Counter.ToString());
+}
+```
+
+## BaseStreamDeckActionWithSettingsModel
+
+```csharp
+public T SettingsModel { get; }
+```
+
+```csharp
+public override Task OnDidReceiveSettings(StreamDeckEventPayload args);
+public override Task OnWillAppear(StreamDeckEventPayload args);
+protected void SetModelProperties(StreamDeckEventPayload args);
+```

docs/articles/template/propertyinspector.md

@@ -0,0 +1,9 @@
+## Property Inspector
+
+There are various types of fields that are supported in property inspector see [Elgato Github PiSamples](https://github.com/elgatosf/streamdeck-pisamples) and [Elgato SDK Documentation](https://developer.elgato.com/documentation/stream-deck/sdk/property-inspector/)
+
+![screenshot](images/screenshot.png)
+
+The above sample from GitHub allows you to drag and drop elements into your html for quick development.
+
+Add it to the `property_inspector.html` file in the project.