Merge branch 'newdoc-guide' into demo-branch-2

.github/workflows/version-bump.yml

@@ -32,6 +32,8 @@ jobs:
       # ----------------------------------------------------------------------- Checkout
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          ssh-key: ${{secrets.CI_DEPLOYMENT_KEY}}
 
       # ----------------------------------------------------------------------- Override the submodule URL
       # This is to support testing release automation in forks, it is disabled for the canonical docs repo
@@ -84,10 +86,3 @@ jobs:
       - name: Push changes
         if: steps.pre-commit-check.outputs.continue == 'true'
         run: git push
-      # The above push will not actually trigger a deployment as actions performed using temporary GitHub Actions tokens
-      # do not trigger events in order to avoid unintentional recursion. As such we manually trigger deployment.
-      - name: Trigger GitHub Pages deployment
-        if: steps.pre-commit-check.outputs.continue == 'true'
-        run: gh workflow run build.yml
-        env:
-          GH_TOKEN: ${{github.token}}

README.md

@@ -4,70 +4,26 @@
 
 This repo contains the technical reference manual for the Bonsai visual programming language, in addition to articles and examples that document the collective knowledge of the Bonsai user community.
 
-# Would you like to contribute to this repo?
+> [!NOTE]  
+> This repo hosts the documentation for the base Bonsai library. Documentation for each new Bonsai package will be hosted in its own repo, for instance, https://github.com/bonsai-rx/machinelearning. 
 
-## Step-by-step guide to getting started as a contributor
+Documentation is built using `docfx`, a static site generator that automatically generates API documentation for .NET projects, and deployed using Github Actions on Github Pages.
 
-1. Fork the "develop" branch of this repository. 
-2. Download and install the latest stable version of [DocFx](https://dotnet.github.io/docfx/index.html) (currently 2.59).
-3. In a Windows Powershell, use the command `docfx docfx.json --serve` to generate a local preview of the documentation website.
-4. If you are working on multiple articles at once, create a descriptively named branch of your fork of the repo for each article. We recommend creating an issue for each article (if it does not already exist), and name the branch `issue-###` where `###` is the issue number.
-5. When you are ready to have your contribution reviewed, commit your edits to the approriate branch of your fork of the repo and create a PR to merge that branch with the "develop" branch of this original repo. Because the "develop" branch was created explicitly to aid collaboration between contributors, pull requests to this branch will be accepted and merged rapidly (at least once a week). 
-6. Once a piece of documentation has been polished, and at least two community members agree that it is ready for a final review, create a pull request to merge with the "main" branch of this repo. At this point, @glopesdev will conduct the final review and quality control check. If the contribution passes this final step, the PR to merge with "main" will be approved and the contribution will be published on the [publicly accessible Bonsai documentation website](https://bonsai-rx.org/docs-wip/).
+We welcome all contributions! For more information please refer to our [Contribution Guide](https://bonsai-rx.org/contribute/).
 
-## Contributor Style Guide 
+# Quick start guide for contributing to documentation
 
-### Why use the "develop" branch?
+These instructions apply to repos that already have a docfx website created.
 
-The "develop" branch is specifically created so that contributors can quickly commit drafts of documentation and collaborate with other community members in order to edit and polish documentation contributions. 
-
-### Re-use/update existing documentation
-
-When working on an article, first check [the old documentation](https://bonsai-rx.org/docs/) to see what written material might already exist for that topic. 
-
-### Including figures
-
-To include a figure or image in an article: 
- - save your figure or image as a `.svg` file, naming the file using the pattern `[article filename]-[figure name].svg`
- - add the figure/image to the **images** folder in this repo
-
-### Standard formatting for operators and operator properties
-
-When referring to operators (also known as nodes in Bonsai), place operator names inside a pair of backticks and double stars (``**`Operator_name`**``) so that the node names render as bold text in code snippet formatting (i.e. **`CameraCapture`**). 
-
-When referring to operator properties, simply place the operator property name inside a pair of backticks (`` `Operator_property_name` ``). 
-
-For both operators and operator properties, link the name to the relevant documentation in the code base, using the [markdown syntax for xref in DocFX](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html). 
-
-For example, the **`DigitalOutput`** node is part of the `Bonsai.Arduino` namespace/package, and contains a property called `PortName`. To reference this specific property you need to specify the full path to it including namespace, operator name and property name, like so: `xref:Bonsai.Arduino.DigitalOutput.PortName`. 
-
-To find out the full path for any node, right-click on the operator of interest in Bonsai and select the option "Go to Definition" or hit F12. The xref will be the namespace + operator name + (optionally) property name.
-
-**Example:**
-
-```markdown
-### **Exercise 7:** Control an LED
-
-![Control an LED](~/images/acquisition-led.svg)
-
-- Insert a [**`Boolean`**](xref:Bonsai.Expressions.BooleanProperty) source.
-- Insert a [**`DigitalOutput`**](xref:Bonsai.Arduino.DigitalOutput) sink.
-- Set the [`Pin`](xref:Bonsai.Arduino.DigitalOutput.Pin) property of the [**`DigitalOutput`**](xref:Bonsai.Arduino.DigitalOutput) operator to 13.
-- Configure the [`PortName`](xref:Bonsai.Arduino.DigitalOutput.PortName) property.
-- Run the workflow and change the [`Value`](xref:Bonsai.Expressions.BooleanProperty.Value) property of the [**`Boolean`**](xref:Bonsai.Expressions.BooleanProperty) operator.
-- **Optional:** Use your mouse to control the LED! Replace the [**`Boolean`**](xref:Bonsai.Expressions.BooleanProperty) operator by a `MouseMove` source (hint: use `GreaterThan`, `LessThan`, or equivalent operators to connect one of the mouse axis to [**`DigitalOutput`**](xref:Bonsai.Arduino.DigitalOutput).
+1. Fork the repository you want to contribute documentation to. 
+2. Ensure that you are working off the `main` branch in your fork and create a descriptively named branch for each article/issue that you want to work on.
+3. Download and install dotnet (https://dotnet.microsoft.com/en-us/download)
+4. Restore `docfx` by running
+```powershell
+dotnet tool restore
 ```
+5. In a Windows Powershell, use the command `dotnet docfx docfx.json --serve` to generate a local preview of the documentation website as you are making changes.
+6. When you are ready to have your contribution reviewed, commit your edits to the approriate branch of your fork and create a pull request to merge that branch with the `main` branch of the original repo.
+7. Community members will be assigned to review the PR and @glopesdev will conduct the final review and quality control check. If the contribution passes this final step, the PR to merge with `main` will be approved and the contribution will be published.
 
-### How to include and/or reference examples of workflows
-
-To include and/or reference an example workflow in an article of the documentation, first create the example workflow in a Bonsai workflow editor. Then open File -> Export -> Image or use keyboard shortcut Ctrl + Shift + E. Name the example according to the following pattern: `articleFileName_workflowName`. This will export the example workflow as both a `.svg` file and a `.bonsai` file. 
-
-Add the `.svg` file to the **images** folder in this repo, and add the `.bonsai` file to the **workflows** folder in this repo. In the text of the article that includes/references this example workflow, add the `.svg` file as an image and link that image to the `.bonsai` file. 
-
-**Example:**
-
-Assuming you want to include `acquisition-example.bonsai`: 
-
-```markdown
-[![Example Workflow](~/images/acquisition-example.svg)](~/workflows/acquisition-example.bonsai)
-```
+For more info, check out the [Documentation with docfx](https://bonsai-rx.org/docs/articles/documentation-docfx.html) and [Documentation Style Guide](https://bonsai-rx.org/docs/articles/documentation-style-guide.html) articles.

articles/create-package.md

@@ -96,6 +96,10 @@ The Bonsai language can be extended with custom packages, which are installed an
     }
     ```
 
+> [!TIP]
+> Use [XML documentation comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags) to document your code. 
+> Check out the [Documentation with docfx](./documentation-docfx.md) article for information on how to use [docfx](https://dotnet.github.io/docfx/index.html) to automatically generate documentation for your package online.
+
 ## Publishing a package project
 
 1. Double-click the name of the project in the Visual Studio Solution Explorer to open up the package metadata.