diff --git a/docs/docs/Get-started.md b/docs/docs/Get-started.md index 73aacb22..b2f15ecf 100644 --- a/docs/docs/Get-started.md +++ b/docs/docs/Get-started.md @@ -23,4 +23,4 @@ This section assumes knowledge of loading programs to and working with the file 1. Run the command `devjson:1 {"deviceKey":"display-1","methodName":"PowerOn", "params": []}`. This will call the method PowerOn() on the device with key "display-1". 1. Run the provided example XPanel SmartGraphics project and connect to your processor at the appropriate IPID. -Next: [Standalone use](~/docs/Standalone-Use.md) +Next: [Standalone use](~/docs/usage/Standalone-Use.md) diff --git a/docs/docs/Home.md b/docs/docs/Home.md index 926bde87..8e0c163e 100644 --- a/docs/docs/Home.md +++ b/docs/docs/Home.md @@ -39,7 +39,7 @@ Thanks! ## Collaboration -Essentials is an open-source project and we encourage collaboration on this community project. For features that may not be useful to the greater community, or for just-plain learning, we want to remind developers to try writing plugins for Essentials. More information can be found here: [Plugins](~/docs/Plugins.md) +Essentials is an open-source project and we encourage collaboration on this community project. For features that may not be useful to the greater community, or for just-plain learning, we want to remind developers to try writing plugins for Essentials. More information can be found here: [Plugins](~/docs/technical-docs/Plugins.md) ### Open-source-collaborative workflow diff --git a/docs/docs/Plugins-Deprecated.md b/docs/docs/Plugins-Deprecated.md index 7f98f7da..c9cb9541 100644 --- a/docs/docs/Plugins-Deprecated.md +++ b/docs/docs/Plugins-Deprecated.md @@ -1,6 +1,6 @@ # Deprecated -**Note : this entry is out of date - please see [Plugins](~/docs/Plugins.md)** +**Note : this entry is out of date - please see [Plugins](~/docs/technical-docs/Plugins.md)** ## What are Essentials Plugins? diff --git a/docs/docs/SIMPL-Bridging-Deprecated.md b/docs/docs/SIMPL-Bridging-Deprecated.md index e2dfa0c2..ccda7aa6 100644 --- a/docs/docs/SIMPL-Bridging-Deprecated.md +++ b/docs/docs/SIMPL-Bridging-Deprecated.md @@ -358,7 +358,7 @@ Example device config: The `DeviceManager` is nothing more than a modified collection of things, and technically those things don't have to be Devices, but must at least implement the `IKeyed` (`PepperDash.Core.IKeyed`) interface (simply so items can be looked up by their key.) Items in the `DeviceManager` that are Devices are run through additional steps of [activation](~/docs/Arch-activate.md#2-pre-activation) at startup. This collection of devices is all interrelated by their string keys. +> The `DeviceManager` is nothing more than a modified collection of things, and technically those things don't have to be Devices, but must at least implement the `IKeyed` (`PepperDash.Core.IKeyed`) interface (simply so items can be looked up by their key.) Items in the `DeviceManager` that are Devices are run through additional steps of [activation](~/docs/technical-docs/Arch-activate.md#2-pre-activation) at startup. This collection of devices is all interrelated by their string keys. In this flat design, we spin up devices, and then introduce them to their "coworkers and bosses" - the other devices and logical units that they will interact with - and get them all operating together to form a running unit. For example: A room configuration will contain a "VideoCodecKey" property and a "DefaultDisplayKey" property. The `DeviceManager` provides the room with the codec or displays having the appropriate keys. What the room does with those is dependent on its coding. @@ -38,4 +38,4 @@ This flat structure ensures that every device in a system exists in one place an ![Architecture overview](~/docs/images/arch-overview.png) -Next: [Configurable lifecycle](~/docs/Arch-lifecycle.md) +Next: [Configurable lifecycle](~/docs/technical-docs/Arch-lifecycle.md) diff --git a/docs/docs/Arch-activate.md b/docs/docs/technical-docs/Arch-activate.md similarity index 95% rename from docs/docs/Arch-activate.md rename to docs/docs/technical-docs/Arch-activate.md index dec6806b..72a9e3eb 100644 --- a/docs/docs/Arch-activate.md +++ b/docs/docs/technical-docs/Arch-activate.md @@ -105,7 +105,7 @@ Each of the three activation phases operates in a try/catch block for each devic In any real-world system, devices and business logic need to talk to each other, otherwise, what's the point of all this coding? When creating your classes and configuration, it is best practice to _try_ not to "plug" one device into another during construction or activation. For example your touchpanel controller class has a `Display1` property that holds the display-1 object. Rather, it may be better to refer to the device as it is stored in the `DeviceManager` when it's needed using the static `DeviceManager.GetDeviceForKey(key)` method to get a reference to the device, which can be cast using various interfaces/class types, and then interacted with. This prevents objects from being referenced in places where the developer may later forget to dereference them, causing memory leak. This will become more important as Essentials becomes more able to be reconfigured at runtime. -As an example, [connection-based routing](~/docs/Connection-based-routing.md#essentials-connection-based-routing) uses these methods. When a route is requested, the collection of tielines and devices is searched for the devices and paths necessary to complete a route, but there are no devices or tie lines that are object-referenced in running code. It can all be torn down and reconfigured without any memory-management dereferencing, setting things to null. +As an example, [connection-based routing](~/docs/technical-docs/Connection-based-routing.md#essentials-connection-based-routing) uses these methods. When a route is requested, the collection of tielines and devices is searched for the devices and paths necessary to complete a route, but there are no devices or tie lines that are object-referenced in running code. It can all be torn down and reconfigured without any memory-management dereferencing, setting things to null. ## Device Initialization @@ -155,4 +155,4 @@ Robust C#-based system code should not depend on "order" or "time" to get runnin When designing new Device-based classes, be it rooms, devices, port controllers, bridges, make them as independent as possible. They could exist alone in a program with no required partner objects, and just quietly exist without failing. We want the system to be fast and flexible, and keeping the interdependence between objects at a minimum improves this flexibility into the future. -Next: [More architecture](~/docs/Arch-topics.md) +Next: [More architecture](~/docs/technical-docs/Arch-topics.md) diff --git a/docs/docs/Arch-lifecycle.md b/docs/docs/technical-docs/Arch-lifecycle.md similarity index 65% rename from docs/docs/Arch-lifecycle.md rename to docs/docs/technical-docs/Arch-lifecycle.md index 42d11deb..5c06658b 100644 --- a/docs/docs/Arch-lifecycle.md +++ b/docs/docs/technical-docs/Arch-lifecycle.md @@ -2,8 +2,8 @@ The diagram below describes how Essentials gets a program up and running. -(The various activation phases are covered in more detail on the [next page](~/docs/Arch-activate.md)) +(The various activation phases are covered in more detail on the [next page](~/docs/technical-docs/Arch-activate.md)) ![Lifecycle](~/docs/images/lifecycle.png) -Next: [Activation phases](~/docs/Arch-activate.md) +Next: [Activation phases](~/docs/technical-docs/Arch-activate.md) diff --git a/docs/docs/Arch-summary.md b/docs/docs/technical-docs/Arch-summary.md similarity index 95% rename from docs/docs/Arch-summary.md rename to docs/docs/technical-docs/Arch-summary.md index 9f7cc014..470bf983 100644 --- a/docs/docs/Arch-summary.md +++ b/docs/docs/technical-docs/Arch-summary.md @@ -16,4 +16,4 @@ The diagram below shows the reference dependencies that exist between the differ ![Architecture drawing](~/docs/images/arch-high-level.png) -Next: [Architecture](~/docs/Arch-1.md) +Next: [Architecture](~/docs/technical-docs/Arch-1.md) diff --git a/docs/docs/Arch-topics.md b/docs/docs/technical-docs/Arch-topics.md similarity index 100% rename from docs/docs/Arch-topics.md rename to docs/docs/technical-docs/Arch-topics.md diff --git a/docs/docs/Communication-Basics.md b/docs/docs/technical-docs/Communication-Basics.md similarity index 100% rename from docs/docs/Communication-Basics.md rename to docs/docs/technical-docs/Communication-Basics.md diff --git a/docs/docs/ConfigurationStructure.md b/docs/docs/technical-docs/ConfigurationStructure.md similarity index 100% rename from docs/docs/ConfigurationStructure.md rename to docs/docs/technical-docs/ConfigurationStructure.md diff --git a/docs/docs/Connection-Based-Routing.md b/docs/docs/technical-docs/Connection-Based-Routing.md similarity index 100% rename from docs/docs/Connection-Based-Routing.md rename to docs/docs/technical-docs/Connection-Based-Routing.md diff --git a/docs/docs/Debugging.md b/docs/docs/technical-docs/Debugging.md similarity index 100% rename from docs/docs/Debugging.md rename to docs/docs/technical-docs/Debugging.md diff --git a/docs/docs/Feedback-Classes.md b/docs/docs/technical-docs/Feedback-Classes.md similarity index 100% rename from docs/docs/Feedback-Classes.md rename to docs/docs/technical-docs/Feedback-Classes.md diff --git a/docs/docs/Glossary-of-Terms.md b/docs/docs/technical-docs/Glossary-of-Terms.md similarity index 100% rename from docs/docs/Glossary-of-Terms.md rename to docs/docs/technical-docs/Glossary-of-Terms.md diff --git a/docs/docs/Plugins.md b/docs/docs/technical-docs/Plugins.md similarity index 100% rename from docs/docs/Plugins.md rename to docs/docs/technical-docs/Plugins.md diff --git a/docs/docs/Supported-Devices.md b/docs/docs/technical-docs/Supported-Devices.md similarity index 100% rename from docs/docs/Supported-Devices.md rename to docs/docs/technical-docs/Supported-Devices.md diff --git a/docs/docs/toc.yml b/docs/docs/toc.yml index bccb3aed..23c9f7fc 100644 --- a/docs/docs/toc.yml +++ b/docs/docs/toc.yml @@ -1,48 +1,52 @@ - name: Get Started With Essentials - href: ../index.md -- href: Get-started.md +- href: Get-started.md +- name: How-to's + items: + - name: How to add an article or doc page + href: how-to/How-to-add-docs.md - name: Usage items: - - href: Standalone-Use.md - - href: SIMPL-Bridging-Updated.md + - href: usage/Standalone-Use.md + - href: usage/SIMPL-Bridging-Updated.md items: - name: Join Maps - href: JoinMaps.md + href: usage/JoinMaps.md - name: Bridging to Hardware Resources - href: Bridging-To-Hardware-Resources.md + href: usage/Bridging-To-Hardware-Resources.md items: - name: GenericComm Bridging - href: GenericComm.md + href: usage/GenericComm.md - name: RelayOutput Bridging - href: RelayOutput.md + href: usage/RelayOutput.md - name: Digital Input Bridging - href: DigitalInput.md + href: usage/DigitalInput.md - name: IR Driver Bridging - href: IR-Driver-Bridging.md + href: usage/IR-Driver-Bridging.md - name: Technical documentation items: - - href: Arch-summary.md + - href: technical-docs/Arch-summary.md - name: Devices and DeviceManager - href: Arch-1.md + href: technical-docs/Arch-1.md - name: Configurable lifecycle - href: Arch-lifecycle.md + href: technical-docs/Arch-lifecycle.md - name: Activation phases - href: Arch-activate.md + href: technical-docs/Arch-activate.md - name: More - href: Arch-topics.md + href: technical-docs/Arch-topics.md - name: Plugins - href: Plugins.md + href: technical-docs/Plugins.md - name: Communication Basics - href: Communication-Basics.md + href: technical-docs/Communication-Basics.md - name: Debugging - href: Debugging.md + href: technical-docs/Debugging.md - name: Feedback Classes - href: Feedback-Classes.md + href: technical-docs/Feedback-Classes.md - name: Connection Based Routing - href: Connection-Based-Routing.md + href: technical-docs/Connection-Based-Routing.md - name: Configuration Structure - href: ConfigurationStructure.md + href: technical-docs/ConfigurationStructure.md - name: Supported Devices - href: Supported-Devices.md + href: technical-docs/Supported-Devices.md - name: Glossary of Terms - href: Glossary-of-Terms.md \ No newline at end of file + href: technical-docs/Glossary-of-Terms.md \ No newline at end of file diff --git a/docs/docs/Bridging-To-Hardware-Resources.md b/docs/docs/usage/Bridging-To-Hardware-Resources.md similarity index 81% rename from docs/docs/Bridging-To-Hardware-Resources.md rename to docs/docs/usage/Bridging-To-Hardware-Resources.md index 1209a5af..a5f410f9 100644 --- a/docs/docs/Bridging-To-Hardware-Resources.md +++ b/docs/docs/usage/Bridging-To-Hardware-Resources.md @@ -6,10 +6,10 @@ One of the most powerful features of Essentials is the ability to bridge SIMPL t Follow the links below for examples of bridging to hardware and network resources. -**[GenericComm Bridging](~/docs/GenericComm.md)** +**[GenericComm Bridging](~/docs/usage/GenericComm.md)** -**[RelayOutput Bridging](~/docs/RelayOutput.md)** +**[RelayOutput Bridging](~/docs/usage/RelayOutput.md)** -**[Digital Input Bridging](~/docs/DigitalInput.md)** +**[Digital Input Bridging](~/docs/usage/DigitalInput.md)** **[Card Frame Bridging](~/docs/CardFrame.md)** diff --git a/docs/docs/DigitalInput.md b/docs/docs/usage/DigitalInput.md similarity index 100% rename from docs/docs/DigitalInput.md rename to docs/docs/usage/DigitalInput.md diff --git a/docs/docs/GenericComm.md b/docs/docs/usage/GenericComm.md similarity index 100% rename from docs/docs/GenericComm.md rename to docs/docs/usage/GenericComm.md diff --git a/docs/docs/IR-Driver-Bridging.md b/docs/docs/usage/IR-Driver-Bridging.md similarity index 100% rename from docs/docs/IR-Driver-Bridging.md rename to docs/docs/usage/IR-Driver-Bridging.md diff --git a/docs/docs/JoinMaps.md b/docs/docs/usage/JoinMaps.md similarity index 100% rename from docs/docs/JoinMaps.md rename to docs/docs/usage/JoinMaps.md diff --git a/docs/docs/RelayOutput.md b/docs/docs/usage/RelayOutput.md similarity index 100% rename from docs/docs/RelayOutput.md rename to docs/docs/usage/RelayOutput.md diff --git a/docs/docs/SIMPL-Bridging-Updated.md b/docs/docs/usage/SIMPL-Bridging-Updated.md similarity index 99% rename from docs/docs/SIMPL-Bridging-Updated.md rename to docs/docs/usage/SIMPL-Bridging-Updated.md index bd648cf0..6ae7642b 100644 --- a/docs/docs/SIMPL-Bridging-Updated.md +++ b/docs/docs/usage/SIMPL-Bridging-Updated.md @@ -286,7 +286,7 @@ Example device config: