Merge pull request #4 from bonsai-rx/docs-dev

Update documentation infrastructure to leverage reusable templates

.bonsai/Bonsai.config

@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="utf-8"?>
+<PackageConfiguration xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+  <Packages>
+    <Package id="Bonsai" version="2.8.2" />
+    <Package id="Bonsai.Core" version="2.8.1" />
+    <Package id="Bonsai.Design" version="2.8.0" />
+    <Package id="Bonsai.Editor" version="2.8.1" />
+    <Package id="jacobslusser.ScintillaNET" version="3.6.3" />
+    <Package id="Markdig" version="0.18.1" />
+    <Package id="Microsoft.Web.WebView2" version="1.0.1823.32" />
+    <Package id="Rx-Core" version="2.2.5" />
+    <Package id="Rx-Interfaces" version="2.2.5" />
+    <Package id="Rx-Linq" version="2.2.5" />
+    <Package id="Rx-PlatformServices" version="2.2.5" />
+    <Package id="SvgNet" version="3.3.3" />
+    <Package id="YamlDotNet" version="13.1.1" />
+  </Packages>
+  <AssemblyReferences>
+    <AssemblyReference assemblyName="Bonsai" />
+    <AssemblyReference assemblyName="Bonsai.Core" />
+    <AssemblyReference assemblyName="Bonsai.Design" />
+    <AssemblyReference assemblyName="Bonsai.Editor" />
+  </AssemblyReferences>
+  <AssemblyLocations>
+    <AssemblyLocation assemblyName="Bonsai" processorArchitecture="MSIL" location="Packages\Bonsai.2.8.2\lib\net48\Bonsai.exe" />
+    <AssemblyLocation assemblyName="Bonsai.Core" processorArchitecture="MSIL" location="Packages\Bonsai.Core.2.8.1\lib\net462\Bonsai.Core.dll" />
+    <AssemblyLocation assemblyName="Bonsai.Design" processorArchitecture="MSIL" location="Packages\Bonsai.Design.2.8.0\lib\net462\Bonsai.Design.dll" />
+    <AssemblyLocation assemblyName="Bonsai.Editor" processorArchitecture="MSIL" location="Packages\Bonsai.Editor.2.8.1\lib\net472\Bonsai.Editor.dll" />
+    <AssemblyLocation assemblyName="Markdig" processorArchitecture="MSIL" location="Packages\Markdig.0.18.1\lib\net40\Markdig.dll" />
+    <AssemblyLocation assemblyName="Microsoft.Web.WebView2.Core" processorArchitecture="MSIL" location="Packages\Microsoft.Web.WebView2.1.0.1823.32\lib\net45\Microsoft.Web.WebView2.Core.dll" />
+    <AssemblyLocation assemblyName="Microsoft.Web.WebView2.WinForms" processorArchitecture="MSIL" location="Packages\Microsoft.Web.WebView2.1.0.1823.32\lib\net45\Microsoft.Web.WebView2.WinForms.dll" />
+    <AssemblyLocation assemblyName="Microsoft.Web.WebView2.Wpf" processorArchitecture="MSIL" location="Packages\Microsoft.Web.WebView2.1.0.1823.32\lib\net45\Microsoft.Web.WebView2.Wpf.dll" />
+    <AssemblyLocation assemblyName="ScintillaNET" processorArchitecture="MSIL" location="Packages\jacobslusser.ScintillaNET.3.6.3\lib\net40\ScintillaNET.dll" />
+    <AssemblyLocation assemblyName="SVG" processorArchitecture="MSIL" location="Packages\SvgNet.3.3.3\lib\net462\SVG.dll" />
+    <AssemblyLocation assemblyName="System.Reactive.Core" processorArchitecture="MSIL" location="Packages\Rx-Core.2.2.5\lib\net45\System.Reactive.Core.dll" />
+    <AssemblyLocation assemblyName="System.Reactive.Interfaces" processorArchitecture="MSIL" location="Packages\Rx-Interfaces.2.2.5\lib\net45\System.Reactive.Interfaces.dll" />
+    <AssemblyLocation assemblyName="System.Reactive.Linq" processorArchitecture="MSIL" location="Packages\Rx-Linq.2.2.5\lib\net45\System.Reactive.Linq.dll" />
+    <AssemblyLocation assemblyName="System.Reactive.PlatformServices" processorArchitecture="MSIL" location="Packages\Rx-PlatformServices.2.2.5\lib\net45\System.Reactive.PlatformServices.dll" />
+    <AssemblyLocation assemblyName="YamlDotNet" processorArchitecture="MSIL" location="Packages\YamlDotNet.13.1.1\lib\net47\YamlDotNet.dll" />
+  </AssemblyLocations>
+  <LibraryFolders>
+    <LibraryFolder path="Packages\Microsoft.Web.WebView2.1.0.1823.32\runtimes\win-arm64\native" platform="arm64" />
+    <LibraryFolder path="Packages\Microsoft.Web.WebView2.1.0.1823.32\runtimes\win-arm64\native_uap" platform="arm64" />
+    <LibraryFolder path="Packages\Microsoft.Web.WebView2.1.0.1823.32\runtimes\win-x64\native" platform="x64" />
+    <LibraryFolder path="Packages\Microsoft.Web.WebView2.1.0.1823.32\runtimes\win-x64\native_uap" platform="x64" />
+    <LibraryFolder path="Packages\Microsoft.Web.WebView2.1.0.1823.32\runtimes\win-x86\native" platform="x86" />
+    <LibraryFolder path="Packages\Microsoft.Web.WebView2.1.0.1823.32\runtimes\win-x86\native_uap" platform="x86" />
+  </LibraryFolders>
+</PackageConfiguration>

.bonsai/NuGet.config

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="utf-8"?>
+<configuration>
+  <packageSources>
+    <add key="Gallery" value="Gallery" />
+    <add key="Bonsai Packages" value="https://www.myget.org/F/bonsai/api/v3/index.json" />
+    <add key="Community Packages" value="https://www.myget.org/F/bonsai-community/api/v3/index.json" />
+  </packageSources>
+</configuration>

.bonsai/Setup.ps1

@@ -0,0 +1,21 @@
+Push-Location $PSScriptRoot
+if (!(Test-Path "./Bonsai.exe")) {
+    $release = "https://github.com/bonsai-rx/bonsai/releases/latest/download/Bonsai.zip"
+    $configPath = "./Bonsai.config"
+    if (Test-Path $configPath) {
+        [xml]$config = Get-Content $configPath
+        $bootstrapper = $config.PackageConfiguration.Packages.Package.where{$_.id -eq 'Bonsai'}
+        if ($bootstrapper) {
+            $version = $bootstrapper.version
+            $release = "https://github.com/bonsai-rx/bonsai/releases/download/$version/Bonsai.zip"
+        }
+    }
+    Invoke-WebRequest $release -OutFile "temp.zip"
+    Move-Item -Path "NuGet.config" "temp.config" -ErrorAction SilentlyContinue
+    Expand-Archive "temp.zip" -DestinationPath "." -Force
+    Move-Item -Path "temp.config" "NuGet.config" -Force -ErrorAction SilentlyContinue
+    Remove-Item -Path "temp.zip"
+    Remove-Item -Path "Bonsai32.exe"
+}
+& .\Bonsai.exe --no-editor
+Pop-Location

.config/dotnet-tools.json

@@ -3,7 +3,7 @@
   "isRoot": true,
   "tools": {
     "docfx": {
-      "version": "2.75.1",
+      "version": "2.75.3",
       "commands": [
         "docfx"
       ]

.github/workflows/docs.yml

@@ -8,30 +8,38 @@ jobs:
   build:
     runs-on: windows-latest
     steps:
-      - uses: actions/checkout@v2
-        name: Checkout
+      - name: Checkout
+        uses: actions/[email protected]
         with:
-          submodules: recursive
+          submodules: true
 
       - name: Setup .NET Core SDK
-        uses: actions/setup-dotnet@v3.2.0
+        uses: actions/setup-dotnet@v4.0.0
         with:
           dotnet-version: 7.x
 
       - name: Setup MSBuild
-        uses: microsoft/setup-msbuild@v1
-
+        uses: microsoft/setup-msbuild@v2
+        
       - name: Restore NuGet Packages
-        run: msbuild -t:restore src\Bonsai.ML.sln
+        run: msbuild -t:restore src/Bonsai.ML.sln
 
+      - name: Build Solution
+        run: msbuild src/Bonsai.ML.sln /p:Configuration=Release
+
       - name: Setup DocFX
         run: dotnet tool restore
 
+      - name: Setup Bonsai
+        working-directory: .bonsai
+        run: ./Setup.ps1
+
       - name: Build Documentation
-        run: dotnet docfx docs/docfx.json
+        working-directory: docs
+        run: ./build.ps1
 
       - name: Publish to github pages
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v3.9.3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: docs/_site

.gitignore

@@ -1,14 +1,12 @@
 .vs
+.venv
 bin
 obj
+Packages
 *.orig
 *.user
 *.suo
 *.exe
+*.exe.settings
+*.exe.old
 *.dll
-*.layout
-.bonsai
-.venv
-*.bak
-.bak
-.config

.gitmodules

@@ -1,3 +1,6 @@
 [submodule "examples"]
 	path = docs/examples
 	url = https://github.com/bonsai-rx/machinelearning-examples.git
+[submodule "docs/bonsai"]
+	path = docs/bonsai
+	url = https://github.com/bonsai-rx/docfx-tools

README.md

@@ -1,3 +1,15 @@
 # Bonsai - Machine Learning
 
-Bonsai Library containing reactive infrastructure for machine learning.
+The Bonsai.ML project is a collection of packages with reactive infrastructure for adding machine learning algorithms in Bonsai. Below you will find the list of packages (and the included subpackages) currently available within the Bonsai.ML collection.
+
+* Bonsai.ML - provides core functionality across all Bonsai.ML packages.
+* Bonsai.ML.LinearDynamicalSystems - package for performing inference of linear dynamical systems. Interfaces with the [lds_python](https://github.com/joacorapela/lds_python) package.
+  - *Bonsai.ML.LinearDynamicalSystems.Kinematics* - subpackage included in the LinearDynamicalSystems package which supports using the Kalman Filter to infer kinematic data.
+* Bonsai.ML.Visualizers - provides a set of visualizers for dynamic graphing/plotting.
+
+> [!NOTE]
+> Bonsai.ML packages are installed through Bonsai's integrated package manager and are typically available for use immediately. However, certain packages may require additional steps for installation. See the dedicated package section for specific guides and documentation.
+
+## Acknowledgments
+
+Development of this package was supported by funding from the Biotechnology and Biological Sciences Research Council [grant number BB/W019132/1].

docs/articles/LinearDynamicalSystems/lds-getting-started.md

@@ -1,6 +1,9 @@
 # Getting Started
 
-This guide shows you how to use the environments created in the previous installation steps to run the package. Depending on your operating system, follow the [activating environments in Windows](#activating-environments---windows) or [activating environments in Linux](#activating-environments---linux) instructions below. *Note* these environments are not configured to run the example workflows. To run the examples, you must install the necessary packages or follow the [Examples](../../../examples/README.md) getting started guide to bootstrap the environments directly from the repo provided.
+This guide shows you how to use the environments created in the previous installation steps to run the package. Depending on your operating system, follow the [activating environments in Windows](#activating-environments---windows) or [activating environments in Linux](#activating-environments---linux) instructions below.
+
+> [!WARNING]
+> These environments are not configured to run the example workflows. To run the examples, you must install the necessary packages or follow the [Examples](~/examples/README.md) getting started guide to bootstrap the environments directly from the repo provided.
 
 ### Activating environments - Windows
 
@@ -13,7 +16,10 @@ Activate the python environment and launch the Bonsai.exe inside the bonsai envi
 
 ### Activating environments - Linux
 
-If you used the Linux environment creation tool, you can activate you bonsai environment the same as you would activate your python virtual environment. You can have both the python and the bonsai environments activated at the same time. *Note* that the order of activating the environments matters so you must activate the python environment first and then the bonsai environment second.
+If you used the Linux environment creation tool, you can activate you bonsai environment the same as you would activate your python virtual environment. You can have both the python and the bonsai environments activated at the same time.
+
+> [!WARNING]
+> The order of activating the environments matters so you must activate the python environment first and the bonsai environment second.
 
 ```cmd
 source .venv/bin/activate
@@ -49,7 +55,8 @@ flowchart LR
 
 ```
 
-*Note* due to the way bonsai interacts with Python, it is necessary for the first 2 steps to complete before instantiating the model. It is important to know that the initialization of the python runtime, loading the module, and creating the model takes time to complete, and that only once the model has been created can inference be performed.
+> [!NOTE]
+> Due to the way Bonsai.ML interacts with Python, it is necessary for the first two steps to complete before instantiating the model. It is important to know that the initialization of the Python runtime, loading the module, and creating the model takes time to complete, and that only once the model has been created can inference be performed.
 
 ### Implementing in Bonsai
 
@@ -77,4 +84,4 @@ The `CreateKFModel` node contains a number of properties which can be useful to
 
 ### Further Examples
 
-For further examples and demonstrations for how this package works, see the [Bonsai - Machine Learning Examples](../../../examples/README.md) section.
+For further examples and demonstrations for how this package works, see the [Bonsai - Machine Learning Examples](~/examples/README.md) section.

docs/articles/LinearDynamicalSystems/lds-installation-guide-linux.md

@@ -1,6 +1,6 @@
 # Installation Guide - Linux
 
-This guide is meant for users to install the package from scratch. *Note* to use this package to run the examples, you must install the additional Bonsai packages required to run each [Example](../../../examples/README.md). Some familiarity with the terminal is necessary.
+This guide is meant for users to install the package from scratch. To use this package to run the examples, you must install the additional Bonsai packages required to run each [Example](~/examples/README.md). Some familiarity with the terminal is necessary.
 
 ## Notes on Installing Bonsai on Linux (Ubuntu)
 
@@ -16,7 +16,8 @@ To get started, you must install the following tools:
 - [Powershell on Linux](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-linux?view=powershell-7.4)
 - [Bonsai-Rx Linux Environment Template](https://github.com/ncguilbeault/bonsai-linux-environment-template)
 
-*Note* be sure to check the python version and dotnet-sdk version to make sure you have the correct version of the tool installed, otherwise the steps in this guide may not work.
+> [!WARNING]
+> Be sure to check the python version and dotnet-sdk version to make sure you have the correct version of the tool installed, otherwise the steps in this guide may not work.
 
 ### Creating Virtual Environments
 
@@ -30,15 +31,17 @@ cd LinearDynamicalSystems
 
 2. Create a python virtual environment.
 
-*Note* this step uses the virtual env package from python to create a virtual environment. If you run into an error during this step, you may have to install the python virtual env package with `sudo apt install python3.10-venv`.
+> [!WARNING]
+> This step uses the virtual env package from python to create a virtual environment. If you run into an error during this step, you may have to install the python virtual env package with `sudo apt install python3.10-venv`.
 
 ```cmd
 python3 -m venv .venv
 ```
 
 3. Create a bonsai environment.
 
-*Note*: this step uses the [bonsai linux environment template tool](https://github.com/ncguilbeault/bonsai-linux-environment-template) for easy creation of linux environments
+> [!NOTE]
+> This step uses the [bonsai linux environment template tool](https://github.com/ncguilbeault/bonsai-linux-environment-template) for easy creation of linux environments
 
 ```cmd
 dotnet new bonsaienvl -o .bonsai
@@ -57,7 +60,7 @@ source .venv/bin/activate
 2. Install the lds_python package
 
 ```cmd
-pip install lds_python@git+https://github.com/joacorapela/lds_python@168d4c05bb4b014998c7d3a2a57d143244a44bdd
+pip install lds_python@git+https://github.com/joacorapela/lds_python@4233363320e021f77f9b3e124846ec2e49c0e741
 ```
 
 If you encounter errors during installation of the lds_python package, you will have to diagnose the issue and install the correct packge dependencies manually.

docs/articles/LinearDynamicalSystems/lds-installation-guide-windows.md

@@ -1,6 +1,6 @@
 # Installation Guide - Windows
 
-This guide is meant for users to install the package from scratch. *Note* to run the examples, users must install the additional Bonsai packages required to run each [Example](../../../examples/README.md). Some familiarity with the command line or powershell terminal is necessary. This guide has only been tested on Windows 10 and 11, so earlier versions of Windows may or may not work.
+This guide is meant for users to install the package from scratch. To run the examples, users must install the additional Bonsai packages required to run each [Example](~/examples/README.md). Some familiarity with the command line or powershell terminal is necessary. This guide has only been tested on Windows 10 and 11, so earlier versions of Windows may or may not work.
 
 ### Dependencies
 
@@ -12,7 +12,8 @@ To get started, you must install the following tools:
 - [Bonsai-Rx Templates tool](https://www.nuget.org/packages/Bonsai.Templates)
 - [Microsoft Visual C++ Redistributable](https://aka.ms/vs/16/release/vc_redist.x64.exe)
 
-*Note* be sure to check the speciic python version and dotnet-sdk version you have installed, as different version than the ones we recommend may or may not work with this guide.
+> [!WARNING]
+> Be sure to check the specific python version and dotnet-sdk version you have installed, as different version than the ones we recommend may or may not work with this guide.
 
 ### Creating Virtual Environments
 
@@ -30,15 +31,17 @@ cd .\LinearDynamicalSystems
 python -m venv .venv
 ```
 
-*Note* If receive an error that says, `python cannot be found`, check to ensure that python is available on the system path. If you just installed python, it may be necessary to restart the terminal.
+> [!TIP]
+> If receive an error that says, `python cannot be found`, check to ensure that python is available on the system path. If you just installed python, it may be necessary to restart the terminal.
 
 3. Create a bonsai environment. When prompted, enter yes to run the powershell setup script.
 
 ```cmd
 dotnet new bonsaienv -o .bonsai
 ```
 
-*Note* If you get an error during this step which says, `Setup.ps1 cannot be loaded because running scripts is disabled`, you need to allow powershell scripts to be executed by users. To do this, you can change the global execution policy by opening a new powershell instance with `Run as Administrator` and use the following command:
+> [!TIP]
+> If you get an error during this step which says, `Setup.ps1 cannot be loaded because running scripts is disabled`, you need to allow powershell scripts to be executed by users. To do this, you can change the global execution policy by opening a new powershell instance with `Run as Administrator` and use the following command:
 
 ```powershell
 set-executionpolicy remotesigned
@@ -62,7 +65,7 @@ Alternatively, you can use the `Setup.cmd` file to setup the bonsai environment
 2. Install the lds_python package
 
 ```cmd
-pip install lds_python@git+https://github.com/joacorapela/lds_python@168d4c05bb4b014998c7d3a2a57d143244a44bdd
+pip install lds_python@git+https://github.com/joacorapela/lds_python@4233363320e021f77f9b3e124846ec2e49c0e741
 ```
 
 If you encounter errors during installation of the lds_python package, you will have to diagnose the issue and install the correct packge dependencies manually.

docs/articles/LinearDynamicalSystems/lds-overview.md

@@ -6,4 +6,4 @@ The LinearDynamicalSystems package provides a Bonsai interface to interact with
 
 Since the package relies on Bonsai **and** python, both Bonsai and Python installation steps are required. We provide detailed instructions for installing the package in a new environment, for example when adding the package to existing workflows, and seperately provide documentation for how to install/run examples which can be bootstrapped directly from the example folder.
 
-To install the package for integrating with existing workflows, see the [Installation Guide - Windows](lds-installation-guide-windows.md) or the [Installation Guide - Linux](lds-installation-guide-linux.md) sections for more information. To head directly to integrating the package into workflows, see the [Getting Started](lds-getting-started.md) section. To test the specific examples provided, check out the [Examples](../../../examples/README.md) tab.
+To install the package for integrating with existing workflows, see the [Installation Guide - Windows](lds-installation-guide-windows.md) or the [Installation Guide - Linux](lds-installation-guide-linux.md) sections for more information. To head directly to integrating the package into workflows, see the [Getting Started](lds-getting-started.md) section. To test the specific examples provided, check out the [Examples](~/examples/README.md) tab.