From f353eb021b1a6b9c8efad53f7291767e3fd83559 Mon Sep 17 00:00:00 2001 From: glopesdev Date: Fri, 8 Mar 2024 00:07:03 +0000 Subject: [PATCH 01/15] Update docfx version and gitignore file --- .config/dotnet-tools.json | 2 +- .gitignore | 10 ++++------ 2 files changed, 5 insertions(+), 7 deletions(-) diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index da22137a..278b6c75 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -3,7 +3,7 @@ "isRoot": true, "tools": { "docfx": { - "version": "2.75.1", + "version": "2.75.3", "commands": [ "docfx" ] diff --git a/.gitignore b/.gitignore index 1dc2875a..50cc126c 100644 --- a/.gitignore +++ b/.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 From 3c9320d1c7aca5b469330776336d6786a2e6540f Mon Sep 17 00:00:00 2001 From: glopesdev Date: Fri, 8 Mar 2024 00:11:20 +0000 Subject: [PATCH 02/15] Add environment for SVG export --- .bonsai/Bonsai.config | 49 +++++++++++++++++++++++++++++++++++++++++++ .bonsai/NuGet.config | 8 +++++++ .bonsai/Setup.cmd | 4 ++++ .bonsai/Setup.ps1 | 21 +++++++++++++++++++ 4 files changed, 82 insertions(+) create mode 100644 .bonsai/Bonsai.config create mode 100644 .bonsai/NuGet.config create mode 100644 .bonsai/Setup.cmd create mode 100644 .bonsai/Setup.ps1 diff --git a/.bonsai/Bonsai.config b/.bonsai/Bonsai.config new file mode 100644 index 00000000..e85ebbb4 --- /dev/null +++ b/.bonsai/Bonsai.config @@ -0,0 +1,49 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/.bonsai/NuGet.config b/.bonsai/NuGet.config new file mode 100644 index 00000000..97e8b731 --- /dev/null +++ b/.bonsai/NuGet.config @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/.bonsai/Setup.cmd b/.bonsai/Setup.cmd new file mode 100644 index 00000000..92d983d9 --- /dev/null +++ b/.bonsai/Setup.cmd @@ -0,0 +1,4 @@ +@echo off +pushd %~dp0 +powershell -ExecutionPolicy Bypass -File ./Setup.ps1 +popd \ No newline at end of file diff --git a/.bonsai/Setup.ps1 b/.bonsai/Setup.ps1 new file mode 100644 index 00000000..01cfba61 --- /dev/null +++ b/.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 \ No newline at end of file From ded89d422a54be71b7ec4b8bb25c5d0c3308d07e Mon Sep 17 00:00:00 2001 From: glopesdev Date: Fri, 8 Mar 2024 00:15:46 +0000 Subject: [PATCH 03/15] Add docfx templates and SVG export module --- .gitmodules | 3 ++ docs/bonsai | 1 + docs/build.ps1 | 2 + docs/docfx.json | 3 +- docs/images/logo.svg | 96 ----------------------------------- docs/template/public/main.css | 35 +------------ docs/template/public/main.js | 58 +++------------------ 7 files changed, 14 insertions(+), 184 deletions(-) create mode 160000 docs/bonsai create mode 100644 docs/build.ps1 delete mode 100644 docs/images/logo.svg diff --git a/.gitmodules b/.gitmodules index ab9c1d96..e27e051b 100644 --- a/.gitmodules +++ b/.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 diff --git a/docs/bonsai b/docs/bonsai new file mode 160000 index 00000000..81ef52fb --- /dev/null +++ b/docs/bonsai @@ -0,0 +1 @@ +Subproject commit 81ef52fb1741ed607a583aa3b640428d70d896a9 diff --git a/docs/build.ps1 b/docs/build.ps1 new file mode 100644 index 00000000..66691c70 --- /dev/null +++ b/docs/build.ps1 @@ -0,0 +1,2 @@ +.\bonsai\modules\Export-Image.ps1 "..\src\Bonsai.ML.Visualizers\bin\Release\net472" +dotnet docfx @args \ No newline at end of file diff --git a/docs/docfx.json b/docs/docfx.json index 988d73ed..2db1eab5 100644 --- a/docs/docfx.json +++ b/docs/docfx.json @@ -70,12 +70,12 @@ "template": [ "default", "modern", + "bonsai/template", "template" ], "globalMetadata": { "_appName": "Bonsai.ML", "_appTitle": "Bonsai.ML", - "_appLogoPath": "images/logo.svg", "_enableNewTab": true, "_enableSearch": true, "pdf": false, @@ -86,7 +86,6 @@ "apiSpecFolder": "apidoc" } }, - "postProcessors": [ "ExtractSearchIndex" ], "markdownEngineName": "markdig", "markdownEngineProperties": { "markdigExtensions": [ diff --git a/docs/images/logo.svg b/docs/images/logo.svg deleted file mode 100644 index aaf57f75..00000000 --- a/docs/images/logo.svg +++ /dev/null @@ -1,96 +0,0 @@ - - - - - - - - - - - - - image/svg+xml - - - - - - - - - - - diff --git a/docs/template/public/main.css b/docs/template/public/main.css index 7035b264..ee56505e 100644 --- a/docs/template/public/main.css +++ b/docs/template/public/main.css @@ -1,34 +1 @@ -.workflow { - border: 1px solid #e3e3e3; - padding: 1px; -} - -.workflow > p > img { - padding-top: 12px; - padding-left: 12px; - padding-right: 12px; -} - -.codeHeader { - box-sizing: content-box; - background-color: #f2f2f2; - color: #171717; - display: flex; - flex-direction: row; - border: 1px solid #e3e3e3; - border-bottom: 0; - margin-top: 16px; - min-height: 30px; -} - -.codeHeader > .language { - padding: 2px 16px; - flex-grow: 1; - line-height: 26px; -} - -.wrap-right > p > img, -.wrap-right > p > a > img { - max-width: 50%; - float: inline-end; -} +@import "workflow.css"; \ No newline at end of file diff --git a/docs/template/public/main.js b/docs/template/public/main.js index 52974c4f..541f7d16 100644 --- a/docs/template/public/main.js +++ b/docs/template/public/main.js @@ -1,52 +1,4 @@ -var WorkflowContainer = { - createCodeHeader: function(text) { - const div = document.createElement("div"); - div.className = "codeHeader"; - div.innerHTML = - ''+ text +''+ - ''+ - ' '+ - ''; - return div; - }, - setCopyAlert: function(element) { - const copyIcon = element.querySelector("i"); - element.classList.add("link-success"); - copyIcon.classList.add("bi-check-lg"); - copyIcon.classList.remove("bi-clipboard"); - setTimeout(function() { - copyIcon.classList.remove("bi-check-lg"); - copyIcon.classList.add("bi-clipboard"); - element.classList.remove("link-success"); - }, 1000); - }, - renderElement: function(element) { - const img = element.querySelector("img"); - const workflowPath = img.src; - img.src = workflowPath.replace(/\.[^.]+$/, ".svg"); - - const codeHeader = WorkflowContainer.createCodeHeader("Workflow"); - const button = codeHeader.querySelector("a"); - button.addEventListener("click", (e) => { - e.preventDefault(); - fetch(workflowPath).then(req => req.text()).then(contents => { - navigator.clipboard.writeText(contents); - WorkflowContainer.setCopyAlert(button); - }); - }); - - const wrap = document.createElement("p"); - const parent = element.parentElement - parent.insertBefore(wrap, element); - wrap.appendChild(codeHeader); - wrap.appendChild(element); - }, - init: async function() { - for (const element of document.getElementsByClassName("workflow")) { - WorkflowContainer.renderElement(element) - } - } -} +import WorkflowContainer from "./workflow.js" export default { defaultTheme: 'auto', @@ -54,6 +6,8 @@ export default { icon: 'github', href: 'https://github.com/bonsai-rx/machinelearning', title: 'GitHub' - }] -} -WorkflowContainer.init(); \ No newline at end of file + }], + start: () => { + WorkflowContainer.init(); + } +} \ No newline at end of file From c238e74f643a7a987f5ce7783b5c46b9cff64634 Mon Sep 17 00:00:00 2001 From: glopesdev Date: Fri, 8 Mar 2024 00:17:58 +0000 Subject: [PATCH 04/15] Remove manually exported SVG files --- docs/workflows/.gitignore | 2 + docs/workflows/KFModelImplementation.svg | 728 ----------------------- 2 files changed, 2 insertions(+), 728 deletions(-) create mode 100644 docs/workflows/.gitignore delete mode 100644 docs/workflows/KFModelImplementation.svg diff --git a/docs/workflows/.gitignore b/docs/workflows/.gitignore new file mode 100644 index 00000000..af455cba --- /dev/null +++ b/docs/workflows/.gitignore @@ -0,0 +1,2 @@ +*.layout +*.svg \ No newline at end of file diff --git a/docs/workflows/KFModelImplementation.svg b/docs/workflows/KFModelImplementation.svg deleted file mode 100644 index 8a75a931..00000000 --- a/docs/workflows/KFModelImplementation.svg +++ /dev/null @@ -1,728 +0,0 @@ - - - - - - - - - - - - - - - - PythonEngine - - - - - - CreateKF - Model - - - - - Observation - - - - - Inferred - Kinematics - - - - - - Create - Runtime - - - - - - Linear - Dynamical - Systems:Load - - - - - - Create - Observation2 - D - - - - - - Perform - Inference - - - - - PythonEngine - - - - - BehaviorData - - - - - Observation - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - From 427a87c7af49532b55c36bcd54279c403098a800 Mon Sep 17 00:00:00 2001 From: glopesdev Date: Fri, 8 Mar 2024 00:24:32 +0000 Subject: [PATCH 05/15] Update action for automated SVG export --- .github/workflows/docs.yml | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 14cf6dcf..f3f3a637 100644 --- a/.github/workflows/docs.yml +++ b/.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/checkout@v4.1.1 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 From 2005590be5c53ddab53d77833e548a0111935a35 Mon Sep 17 00:00:00 2001 From: glopesdev Date: Fri, 8 Mar 2024 00:32:41 +0000 Subject: [PATCH 06/15] Fix broken links --- docs/articles/LinearDynamicalSystems/lds-getting-started.md | 4 ++-- .../LinearDynamicalSystems/lds-installation-guide-linux.md | 2 +- .../LinearDynamicalSystems/lds-installation-guide-windows.md | 2 +- docs/articles/LinearDynamicalSystems/lds-overview.md | 2 +- docs/index.md | 4 ++-- docs/toc.yml | 2 +- 6 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/articles/LinearDynamicalSystems/lds-getting-started.md b/docs/articles/LinearDynamicalSystems/lds-getting-started.md index dfabf070..37007e91 100644 --- a/docs/articles/LinearDynamicalSystems/lds-getting-started.md +++ b/docs/articles/LinearDynamicalSystems/lds-getting-started.md @@ -1,6 +1,6 @@ # 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. *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. ### Activating environments - Windows @@ -77,4 +77,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. diff --git a/docs/articles/LinearDynamicalSystems/lds-installation-guide-linux.md b/docs/articles/LinearDynamicalSystems/lds-installation-guide-linux.md index 12bf4f3c..73e7096a 100644 --- a/docs/articles/LinearDynamicalSystems/lds-installation-guide-linux.md +++ b/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. *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. ## Notes on Installing Bonsai on Linux (Ubuntu) diff --git a/docs/articles/LinearDynamicalSystems/lds-installation-guide-windows.md b/docs/articles/LinearDynamicalSystems/lds-installation-guide-windows.md index 4b31c951..533df8d5 100644 --- a/docs/articles/LinearDynamicalSystems/lds-installation-guide-windows.md +++ b/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. *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. ### Dependencies diff --git a/docs/articles/LinearDynamicalSystems/lds-overview.md b/docs/articles/LinearDynamicalSystems/lds-overview.md index a4025765..72423f73 100644 --- a/docs/articles/LinearDynamicalSystems/lds-overview.md +++ b/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. diff --git a/docs/index.md b/docs/index.md index 8a4830d6..3384b0c2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,6 +7,6 @@ Welcome to the Bonsai.ML website. For documention on installation, getting started and more, head to [Docs](articles/introduction.md) -For detailed technical reference, head to [API](api/Bonsai.ML.yml) +For detailed technical reference, head to [API](api/Bonsai.ML.LinearDynamicalSystems.yml) -For examples of how Bonsai.ML can be used, head to [Examples](../examples/README.md) +For examples of how Bonsai.ML can be used, head to [Examples](~/examples/README.md) diff --git a/docs/toc.yml b/docs/toc.yml index 06bc11e7..3b4f64fc 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -3,4 +3,4 @@ - name: API href: api/ - name: Examples - href: ../examples/docs/ \ No newline at end of file + href: examples/docs/ \ No newline at end of file From 28bdc2232cbe51fa650c7a07aea0367150f7ee5a Mon Sep 17 00:00:00 2001 From: glopesdev Date: Fri, 8 Mar 2024 00:44:56 +0000 Subject: [PATCH 07/15] Move introduction to landing page --- docs/articles/introduction.md | 10 ---------- docs/articles/toc.yml | 2 +- docs/docfx.json | 4 ++-- docs/index.md | 16 +++++++--------- 4 files changed, 10 insertions(+), 22 deletions(-) delete mode 100644 docs/articles/introduction.md diff --git a/docs/articles/introduction.md b/docs/articles/introduction.md deleted file mode 100644 index 208bc5f3..00000000 --- a/docs/articles/introduction.md +++ /dev/null @@ -1,10 +0,0 @@ -# Introduction - -The Bonsai.ML project is a collection of Bonsai packages 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](LinearDynamicalSystems/lds-overview.md) - package for performing inference of linear dynamical systems. Interfaces with the [lds_python](https://github.com/joacorapela/lds_python) package. Requires additional installation steps (see [here](LinearDynamicalSystems/lds-overview.md)). - - *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. diff --git a/docs/articles/toc.yml b/docs/articles/toc.yml index 7bf93ebf..7fe8112f 100644 --- a/docs/articles/toc.yml +++ b/docs/articles/toc.yml @@ -1,5 +1,5 @@ - name: Introduction - href: introduction.md + href: ../index.md - name: Packages items: - name: Bonsai.ML.LinearDynamicalSystems diff --git a/docs/docfx.json b/docs/docfx.json index 2db1eab5..efa7ff91 100644 --- a/docs/docfx.json +++ b/docs/docfx.json @@ -74,12 +74,12 @@ "template" ], "globalMetadata": { - "_appName": "Bonsai.ML", + "_appName": "Bonsai - ML", "_appTitle": "Bonsai.ML", "_enableNewTab": true, "_enableSearch": true, "pdf": false, - "_appFooter": "© 2024 Bonsai Foundation and Contributors - Licensed under CC BY-SA 4.0. - Made with docfx", + "_appFooter": "© 2024 Bonsai Foundation CIC and Contributors. Made with docfx", "_gitContribute": { "repo": "https://github.com/bonsai-rx/machinelearning", "branch": "main", diff --git a/docs/index.md b/docs/index.md index 3384b0c2..53d1f7f1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,12 +1,10 @@ ---- -_layout: landing ---- -# Bonsai.ML +# Introduction -Welcome to the Bonsai.ML website. +The Bonsai.ML project is a collection of Bonsai packages 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. -For documention on installation, getting started and more, head to [Docs](articles/introduction.md) +* Bonsai.ML - provides core functionality across all Bonsai.ML packages. +* [Bonsai.ML.LinearDynamicalSystems](./articles/LinearDynamicalSystems/lds-overview.md) - package for performing inference of linear dynamical systems. Interfaces with the [lds_python](https://github.com/joacorapela/lds_python) package. Requires additional installation steps (see [here](./articles/LinearDynamicalSystems/lds-overview.md)). + - *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. -For detailed technical reference, head to [API](api/Bonsai.ML.LinearDynamicalSystems.yml) - -For examples of how Bonsai.ML can be used, head to [Examples](~/examples/README.md) +*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. From f8c99d6ac6469c1e687c3bd8ac1c3e533f1af0ae Mon Sep 17 00:00:00 2001 From: glopesdev Date: Fri, 8 Mar 2024 00:59:32 +0000 Subject: [PATCH 08/15] Convert notes into alert boxes --- .../LinearDynamicalSystems/lds-getting-started.md | 13 ++++++++++--- .../lds-installation-guide-linux.md | 11 +++++++---- .../lds-installation-guide-windows.md | 11 +++++++---- docs/index.md | 3 ++- 4 files changed, 26 insertions(+), 12 deletions(-) diff --git a/docs/articles/LinearDynamicalSystems/lds-getting-started.md b/docs/articles/LinearDynamicalSystems/lds-getting-started.md index 37007e91..54b5089c 100644 --- a/docs/articles/LinearDynamicalSystems/lds-getting-started.md +++ b/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 diff --git a/docs/articles/LinearDynamicalSystems/lds-installation-guide-linux.md b/docs/articles/LinearDynamicalSystems/lds-installation-guide-linux.md index 73e7096a..261e26e2 100644 --- a/docs/articles/LinearDynamicalSystems/lds-installation-guide-linux.md +++ b/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,7 +31,8 @@ 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 @@ -38,7 +40,8 @@ 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 diff --git a/docs/articles/LinearDynamicalSystems/lds-installation-guide-windows.md b/docs/articles/LinearDynamicalSystems/lds-installation-guide-windows.md index 533df8d5..c623f345 100644 --- a/docs/articles/LinearDynamicalSystems/lds-installation-guide-windows.md +++ b/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,7 +31,8 @@ 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. @@ -38,7 +40,8 @@ python -m venv .venv 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 diff --git a/docs/index.md b/docs/index.md index 53d1f7f1..9d310390 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,4 +7,5 @@ The Bonsai.ML project is a collection of Bonsai packages for adding machine lear - *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. +> [!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. From 7b6e3664cae50996c1197565e798e6175ff6f5c9 Mon Sep 17 00:00:00 2001 From: glopesdev Date: Fri, 8 Mar 2024 01:10:03 +0000 Subject: [PATCH 09/15] Update README file and add funding statement --- README.md | 14 +++++++++++++- docs/index.md | 6 +++++- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b0b2c8b3..dd326541 100644 --- a/README.md +++ b/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]. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 9d310390..7a6eda1c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ # Introduction -The Bonsai.ML project is a collection of Bonsai packages 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. +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](./articles/LinearDynamicalSystems/lds-overview.md) - package for performing inference of linear dynamical systems. Interfaces with the [lds_python](https://github.com/joacorapela/lds_python) package. Requires additional installation steps (see [here](./articles/LinearDynamicalSystems/lds-overview.md)). @@ -9,3 +9,7 @@ The Bonsai.ML project is a collection of Bonsai packages for adding machine lear > [!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]. \ No newline at end of file From 706e5817a26d5e9399a21995ed7058953c922bfa Mon Sep 17 00:00:00 2001 From: glopesdev Date: Fri, 8 Mar 2024 01:51:39 +0000 Subject: [PATCH 10/15] Update examples submodule --- docs/examples | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/examples b/docs/examples index 949d4d1b..18c25699 160000 --- a/docs/examples +++ b/docs/examples @@ -1 +1 @@ -Subproject commit 949d4d1bd63ca54c5183e7ebef9079c3b7666829 +Subproject commit 18c256991c503f43c353667d4a357f34f5d17b5f From d11b1f46df7350078d8ebeb5dbec3b5048e33a47 Mon Sep 17 00:00:00 2001 From: glopesdev Date: Fri, 8 Mar 2024 02:33:21 +0000 Subject: [PATCH 11/15] Add automatic export of example workflows --- docs/bonsai | 2 +- docs/build.ps1 | 13 +++++++++++++ docs/examples | 2 +- 3 files changed, 15 insertions(+), 2 deletions(-) diff --git a/docs/bonsai b/docs/bonsai index 81ef52fb..8e93a915 160000 --- a/docs/bonsai +++ b/docs/bonsai @@ -1 +1 @@ -Subproject commit 81ef52fb1741ed607a583aa3b640428d70d896a9 +Subproject commit 8e93a91590cdb751e7dc878d09ae9605cd9263f4 diff --git a/docs/build.ps1 b/docs/build.ps1 index 66691c70..f01589fa 100644 --- a/docs/build.ps1 +++ b/docs/build.ps1 @@ -1,2 +1,15 @@ .\bonsai\modules\Export-Image.ps1 "..\src\Bonsai.ML.Visualizers\bin\Release\net472" +$exampleEnvironments = Get-ChildItem -Directory -Recurse -Filter ".bonsai" -Path "examples" +foreach ($environment in $exampleEnvironments) +{ + # bootstrap environment + $galleryPath = Join-Path $environment.FullName "Gallery" + Get-ChildItem -Path "..\src\bin\Release" -Filter *.nupkg | Copy-Item -Destination $galleryPath + . (Join-Path $environment.FullName "Setup.ps1") + + # export example workflows + $workflowPath = $environment.Parent.FullName + $bootstrapperPath = Join-Path $environment.FullName "Bonsai.exe" + .\bonsai\modules\Export-Image.ps1 -workflowPath $workflowPath -bootstrapperPath $bootstrapperPath +} dotnet docfx @args \ No newline at end of file diff --git a/docs/examples b/docs/examples index 18c25699..2601fe9a 160000 --- a/docs/examples +++ b/docs/examples @@ -1 +1 @@ -Subproject commit 18c256991c503f43c353667d4a357f34f5d17b5f +Subproject commit 2601fe9a081b9a215ce8bc9f3e153f299d37230b From fe93ccd7fbcdf1b4eb185c882886c7d71baf92d7 Mon Sep 17 00:00:00 2001 From: glopesdev Date: Fri, 8 Mar 2024 02:45:23 +0000 Subject: [PATCH 12/15] Update examples submodule to fix broken links --- docs/examples | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/examples b/docs/examples index 2601fe9a..fb462f58 160000 --- a/docs/examples +++ b/docs/examples @@ -1 +1 @@ -Subproject commit 2601fe9a081b9a215ce8bc9f3e153f299d37230b +Subproject commit fb462f589fad6bc964326db88fe0633c2b537a9b From 406f80ef6237c324c5eafbecc54bca28e81d0c7d Mon Sep 17 00:00:00 2001 From: glopesdev Date: Fri, 8 Mar 2024 10:46:52 +0000 Subject: [PATCH 13/15] Remove cmd bootstrapper script --- .bonsai/Setup.cmd | 4 ---- 1 file changed, 4 deletions(-) delete mode 100644 .bonsai/Setup.cmd diff --git a/.bonsai/Setup.cmd b/.bonsai/Setup.cmd deleted file mode 100644 index 92d983d9..00000000 --- a/.bonsai/Setup.cmd +++ /dev/null @@ -1,4 +0,0 @@ -@echo off -pushd %~dp0 -powershell -ExecutionPolicy Bypass -File ./Setup.ps1 -popd \ No newline at end of file From 0154d2d4c624c700f81215e26999cf34a394e4b7 Mon Sep 17 00:00:00 2001 From: glopesdev Date: Fri, 8 Mar 2024 10:54:53 +0000 Subject: [PATCH 14/15] Update lds_python version --- .../LinearDynamicalSystems/lds-installation-guide-linux.md | 2 +- .../LinearDynamicalSystems/lds-installation-guide-windows.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/articles/LinearDynamicalSystems/lds-installation-guide-linux.md b/docs/articles/LinearDynamicalSystems/lds-installation-guide-linux.md index 261e26e2..c365e980 100644 --- a/docs/articles/LinearDynamicalSystems/lds-installation-guide-linux.md +++ b/docs/articles/LinearDynamicalSystems/lds-installation-guide-linux.md @@ -60,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. diff --git a/docs/articles/LinearDynamicalSystems/lds-installation-guide-windows.md b/docs/articles/LinearDynamicalSystems/lds-installation-guide-windows.md index c623f345..c6251a04 100644 --- a/docs/articles/LinearDynamicalSystems/lds-installation-guide-windows.md +++ b/docs/articles/LinearDynamicalSystems/lds-installation-guide-windows.md @@ -65,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. From 44cda1c5f5099db41d41974a6ad4db4fb89c7dc6 Mon Sep 17 00:00:00 2001 From: glopesdev Date: Fri, 8 Mar 2024 11:02:57 +0000 Subject: [PATCH 15/15] Update example workflows --- docs/examples | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/examples b/docs/examples index fb462f58..a932c855 160000 --- a/docs/examples +++ b/docs/examples @@ -1 +1 @@ -Subproject commit fb462f589fad6bc964326db88fe0633c2b537a9b +Subproject commit a932c8550f32e808afc38bbb65a29ab85958b331