open-ephys · cjsha · Sep 6, 2024 · Sep 6, 2024 · Sep 6, 2024 · Sep 9, 2024
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -26,7 +26,7 @@ jobs:
 
       # Check for missing / broken links in the *.md files prior to building the website
       - name: Check Documentation Links
-        run: dotnet DocLinkChecker -v -f .github/workflows/DocLinkChecker.config
+        run: .\docfx-utils.ps1 -d
 
       - name: Setup DocFX
         run: dotnet tool restore
@@ -36,7 +36,7 @@ jobs:
         run: .\Setup.ps1
 
       - name: Build Documentation
-        run: .\build.ps1 --logLevel Warning --warningsAsErrors
+        run: .\docfx-utils.ps1 -b
 
       - name: Upload Artifact
         uses: actions/upload-artifact@v4

diff --git a/README.md b/README.md
@@ -75,13 +75,13 @@ git submodule update --recursive --remote
 The following three commands are run remotely by remote GitHub Actions serve upon pushing to a branch. The branch will not be able to merge to main unless all three commands complete successfully without any errors. Confirm that they can complete successfully without errors locally before committing and pushing. Otherwise, the branch becomes cluttered with potentially several attempts to pass the link-check process. Run: 
 
 ``` console
-.\build.ps1 --logLevel Warning --warningsAsErrors
+.\build.ps1 --logLevel Suggestion --warningsAsErrors
 dotnet DocLinkChecker -v -f .github/workflows/DocLinkChecker.config
 ```
 
 If the above command fails because "you must install or update .NET", follow the URL from the failed command's output or [this one](https://dotnet.microsoft.com/en-us/download/dotnet/6.0/runtime?cid=getdotnetcore&os=windows&arch=x64) to download and install .NET runtime 6. Dotnet supports simultaneous installation of several .NET runtime versions, and version 6 is required to run the DocLinkChecker.
 
-The above set of commands can also be run using the `docfx-util.ps1` Powershell script. Specifically, run `./docfx-util.ps1 -d` in the repo's root directory. 
+The above set of commands can also be run using the `docfx-utils.ps1` Powershell script. Specifically, run `./docfx-utils.ps1 -d` in the repo's root directory to run DocLinkChecker, and run `./docfx-utils.ps1 -b` to build the site. 
 
 To run the next command, install [Lychee](https://github.com/lycheeverse/lychee?tab=readme-ov-file) by following [these instructions](https://github.com/lycheeverse/lychee?tab=readme-ov-file#installation). If you are use Windows and download a Lychee executable, amend the below command according to the location and version of your Lychee executable, and run it.
 
@@ -91,25 +91,26 @@ To run the next command, install [Lychee](https://github.com/lycheeverse/lychee?
 
 If you use a different operating systems and a different methods of installation, the above command might require additional amendments. 
 
-The above command can also be run using the `docfx-util.ps1` Powershell script. Specifically, run `./docfx-util.ps1 -l <path/to/lychee.exe>` in the repo's root directory. 
+The above command can also be run using the `docfx-utils.ps1` Powershell script. Specifically, run `./docfx-utils.ps1 -l <path/to/lychee.exe>` in the repo's root directory. 
 
-All three link-checking commands can be run with the following command: `./docfx-util.ps1 -a` in the repo's root directory. This command additionally cleans remaining artifacts from past builds before performing all the link-checking commands. This is the most robust and expedient way to confirm that the repo will pass the link checks when pushed. 
+All three link-checking commands can be run with the following command: `./docfx-utils.ps1 -a` in the repo's root directory. This command additionally cleans remaining artifacts from past builds before performing all the link-checking commands. This is the most robust and expedient way to confirm that the repo will pass the link checks when pushed. 
 
 ### docfx-utils.ps1
 
 This is summary of docfx-utils.ps1 list members. They are described above, but they are also described below for ease-of-finding:
 
 - `docfx-utils.ps1 -c` cleans cached files/removes artifacts from previous builds.
 - `docfx-utils.ps1 -b` exports SVGs and builds the docs.
-- `docfx-utils.ps1 -l <path/to/lychee.exe>` checks for broken/missing links and references.
+- `docfx-utils.ps1 -d` check the markdown files for broken references using DocLinkChecker.
+- `docfx-utils.ps1 -l <path/to/lychee.exe>` checks for broken/missing links and references using lychee.
 - `docfx-utils.ps1 -a <path/to/lychee.exe>` performs all of the above steps.
 
 `docfx-utils.ps1 -l` and `docfx-utils.ps1 -a` will not run without a path to a lychee executable.   
 
 > [!NOTE]  
 > The docfx-utils.ps1 script (.ps1 PowerShell scripts in general) must be run in PowerShell.
 
-These commands do not serve the docs. Serve them by running `dotnet docfx serve`.
+These commands do not serve the docs. Serve them by running `dotnet docfx serve _site`. Note that this will not work if the documentation website has not been previously built. If the SVGs have been created, but the `_site` folder is empty and the only option that needs to be run is building the documentation pages, run `dotnet docfx --serve` to build the pages and automatically serve them.
 
 ## `dotnet docfx`
 
@@ -172,15 +173,15 @@ If local html pages don't appear to be updating, hard refresh website pages in b
 If there are discrepancies between local and remote builds:
 
 * Confirm local and remote docfx versions are consistent. This inconsistency can occur when, for example, running `docfx` instead of `dotnet docfx` or running `dotnet tool restore --configfile <configfile>` on another config file other than the one in this repo.
-* Clear any locally cached files that aren't available remotely. Such files exist in the `api` directory (though care to not delete the `.gitignore` in that directory), the `_site` directory, and the workflows directory. Run `./docfx-util.ps1 -c` to clean artifacts from previous builds. 
+* Clear any locally cached files that aren't available remotely. Such files exist in the `api` directory (though care to not delete the `.gitignore` in that directory), the `_site` directory, and the workflows directory. Run `./docfx-utils.ps1 -c` to clean artifacts from previous builds. 
 
 ## Docs Maintainability
 
 ### Creating Edited Screenshots
 
 There are webpages with edited screenshots of Bonsai. The source material (.xcf GIMP files) belongs in the img-src directory for ease of maintenance. The headers below describe how you can quickly create a new screenshot.
 
-To take the screenshot (in Windows), use the `Windows+Shift+S` hotkey, select the `Window` option, and select the window you would like to screenshot. Cris's preference is to take a screenshot against a grey background (e.g. Cris creates a (R: 127, G: 127, B: 127) background in GIMP) because some of the background makes it into the screenshot.
+To take the screenshot (in Windows), use the `Windows+Shift+S` hotkey, select the `Window` option, and select the window you would like to screenshot. The preference is to take a screenshot against a grey background (e.g. create a (R: 127, G: 127, B: 127) background in GIMP) because some of the background makes it into the screenshot.
 
 #### Bonsai Package Manager Screenshot Edits
 

diff --git a/articles/devices/bno055-neuropixelsv1e.md b/articles/devices/bno055-neuropixelsv1e.md
diff --git a/articles/devices/bno055-neuropixelsv2e.md b/articles/devices/bno055-neuropixelsv2e.md
diff --git a/articles/devices/bno055.md b/articles/devices/bno055.md
diff --git a/articles/devices/breakoutanalogio.md b/articles/devices/breakoutanalogio.md
diff --git a/articles/devices/breakoutdigitalio.md b/articles/devices/breakoutdigitalio.md
diff --git a/articles/devices/electricalstimulator.md b/articles/devices/electricalstimulator.md
diff --git a/articles/devices/heartbeat.md b/articles/devices/heartbeat.md
diff --git a/articles/devices/memorymonitor.md b/articles/devices/memorymonitor.md
diff --git a/articles/devices/neuropixelsv1e.md b/articles/devices/neuropixelsv1e.md
diff --git a/articles/devices/neuropixelsv2e.md b/articles/devices/neuropixelsv2e.md
diff --git a/articles/devices/neuropixelsv2ebeta.md b/articles/devices/neuropixelsv2ebeta.md
diff --git a/articles/devices/opticalstimulator.md b/articles/devices/opticalstimulator.md
diff --git a/articles/devices/rhd2164.md b/articles/devices/rhd2164.md
diff --git a/articles/devices/ts4231.md b/articles/devices/ts4231.md
diff --git a/articles/getting-started/bonsai-usage.md b/articles/getting-started/bonsai-usage.md
@@ -1,5 +1,5 @@
 ---
-uid: BonsaiUsage
+uid: bonsai-usage
 title: Bonsai Usage
 ---
 

diff --git a/articles/getting-started/getting-started.md b/articles/getting-started/getting-started.md
@@ -3,6 +3,9 @@ uid: GettingStarted
 title: Getting Started
 ---
 
-Welcome to the user guide! The next few pages will teach you what ONIX is, how to download and install Bonsai, open a new file, place operators (and understand what an operator is), reorder a workflow, run a workflow, and visualize data.
+Welcome to the user guide! The next few pages are dedicated to users who are unfamiliar with ONIX and Bonsai, and will teach them what ONIX is, how to download and install Bonsai, open a new file, place operators (and understand what an operator is), reorder a workflow, run a workflow, and finally visualize data.
 
-Those who are already familiar with Bonsai and are looking for how to acquire data from a particular device or headstage should have a look at the the table of contents on the left, which contains entries for each all hardware supported by the library. Choose a page to learn more about the hardware and view a functional workflow that can be copy/pasted directly into Bonsai to aid in quickly setting up and collecting data from a system.
+For those who are already familiar with Bonsai and are looking for a particular device or headstage to learn more about the hardware and how to utilize it, the table of contents on the left contains entries for each available device and headstage. Choose a page to learn more about the hardware and view a fully complete workflow that can be copied directly into Bonsai to aid in quickly setting up and collecting data from a system.
+
+> [!Note]
+> Add links to relevant pages for each of the action items listed here
diff --git a/articles/getting-started/index.md b/articles/getting-started/index.md
@@ -0,0 +1,12 @@
+---
+uid: getting-started
+title: Getting Started
+---
+
+Welcome to the user guide! The next few pages are dedicated to users who are unfamiliar with ONIX
+and Bonsai, and will teach them what ONIX is, how to download and install Bonsai, open a new file,
+place operators (and understand what an operator is), reorder a workflow, run a workflow, and
+finally visualize data.
+
+For those who are already familiar with Bonsai and Onix and are looking for a particular device or headstage
+to learn about and how to utilize, visit the <xref:hardware>.
diff --git a/articles/getting-started/initialize-oni-context.md b/articles/getting-started/initialize-oni-context.md
@@ -1,9 +1,9 @@
 ---
-uid: InitializeOniContext
+uid: initialize-onicontext
 title: Initialize the ONI Context
 ---
 
-The [`CreateContext`](xref:OpenEphys.Onix1.CreateContext) operator initializes the acquisition context, and it should be the first operator you add to your workflow as it provides access to the hardware device table for all other configuration operators. There are several different ways to find this operator and add it to the workflow:
+The [`CreateContext`](xref:OpenEphys.Onix1.CreateContext) operator initializes the acquisition context, and it should be the first operator you add to your workflow as it provides access to the hardware device table for all other configuration operators. There are several different ways to find this operator and add it to the deviceDirectory:
 
 1. From the Bonsai editor, navigate to the toolbox on the left side of the screen and expand the **Source** section. Next, expand the **OpenEphys.Onix1** section, and find the `CreateContext` line. The operator can then be added by either double-clicking it, or dragging and dropping the operator into the workflow.
 

diff --git a/articles/getting-started/install-configure-bonsai.md b/articles/getting-started/install-configure-bonsai.md
@@ -1,5 +1,5 @@
 ---
-uid: BonsaiInstallationAndConfiguration
+uid: install-configure-bonsai
 title: Bonsai Installation and Configuration
 ---
 
@@ -29,6 +29,18 @@ The following packages required to run the workflows in this documentation are:
 > [!TIP]
 > Additional packages will allow you to extend the functionality of ONIX hardware beyond the scope of this documentation. There are packages that allow ONIX be combined with [visual psychophysics](https://bonsai-rx.org/docs/tutorials/vision-psychophysics.html), [markerless pose estimation](https://bonsai-rx.org/sleap/), [HARP behavioral devices](https://harp-tech.org/), and much more.
 
+### OpenEphys.Onix1.Design
+
+To install the `OpenEphys.Onix1.Design` package [open the package manager](#open-bonsai-package-manager) and:
+
+1.  Click the `Browse` tab.
+1.  Set `Package source` to `All` or `NuGet`.
+1.  Search `OpenEphys.Onix1.Design`.
+1.  Click `Install`.
+1.  Click `I Accept` when the license agreement window appears.
+
+![Bonsai OpenEphys.Onix1.Design Install Screenshot](../../images/bonsai-install-OpenEphys.Onix1.Design.webp){width=650px}
+
 ### Bonsai.StarterPack
 
 To install the `Bonsai.StarterPack` package [open the package manager](#open-bonsai-package-manager) and:
@@ -51,18 +63,6 @@ To install the `OpenEphys.Commutator` package [open the package manager](#open-b
 
 ![Bonsai OpenEphys.Commutator Install Screenshot](../../images/bonsai-install-OpenEphys.Commutator.webp){width=650px}
 
-### OpenEphys.Onix1.Design
-
-To install the `OpenEphys.Onix1.Design` package [open the package manager](#open-bonsai-package-manager) and:
-
-1.  Click the `Browse` tab.
-1.  Set `Package source` to `All` or `NuGet`.
-1.  Search `OpenEphys.Onix1.Design`.
-1.  Click `Install`.
-1.  Click `I Accept` when the license agreement window appears.
-
-![Bonsai OpenEphys.Onix1.Design Install Screenshot](../../images/bonsai-install-OpenEphys.Onix1.Design.webp){width=650px}
-
 ## Update Packages in Bonsai
 
 It is good practice to periodically check for package updates. To do this, [open the package manager](#open-bonsai-package-manager) and:
@@ -90,4 +90,4 @@ Sometimes it is helpful to uninstall packages. [Open the package manager](#open-
 
 ## Next Steps
 
-Now that Bonsai has been installed and configured, it is time to start constructing a workflow to capture data from your ONIX system. The following sections give a high-level understanding of how Bonsai is organized, and some of the ONIX-specific concepts that will be useful for learning how to work with the operators. If you are familiar with Bonsai, you might want to skip to the <xref:headstages-index> section.
+Now that Bonsai has been installed and configured, it is time to start constructing a workflow to capture data from your ONIX system. The following sections give a high-level understanding of how Bonsai is organized, and some of the ONIX-specific concepts that will be useful for learning how to work with the operators. If you are familiar with Bonsai, you might want to skip to the <xref:tutorials> section.
diff --git a/articles/getting-started/next-steps.md b/articles/getting-started/next-steps.md
@@ -1,10 +1,10 @@
 ---
-uid: NextSteps
+uid: next-steps
 title: Next Steps
 ---
 
-Continue browsing <xref:GettingStarted> and check out specific operators on the left to see how to configure each operator, as well as some ways to visualize data. Each page will have a fully functional workflow that can be copied into Bonsai to provide an easy starting point for generating data.
+Continue browsing <xref:getting-started> and check out specific operators on the left to see how to configure each operator, as well as some ways to visualize data. Each page will have a fully functional workflow that can be copied into Bonsai to provide an easy starting point for generating data.
 
 For more technical information on each operator, head to the <xref:OpenEphys.Onix1> to see a more developer-focused view of each operator.
 
-More complex and in-depth tutorials for placing multiple operators and moving towards generating data in an experimental setting can be found in the <xref:TutorialsLandingPage>.
+More complex and in-depth tutorials for placing multiple operators and moving towards generating data in an experimental setting can be found in the <xref:tutorials>.
diff --git a/articles/getting-started/node-types.md → articles/getting-started/operator-types.md b/articles/getting-started/node-types.md → articles/getting-started/operator-types.md
@@ -1,5 +1,5 @@
 ---
-uid: OperatorTypes
+uid: operator-types
 title: Operator Types
 ---