Update "Create a Package" article for Bonsai 2.9

[banchan86]

Part of #107.

This revision updates the "Create a Package" with the updated Bonsai.Templates introduced in bonsai-rx/bonsai#2306.

I struggled a bit with this article. Initially, I considered just updating the point-and-click instructions for Visual Studio and adding a separate section for the command-line interface commands. However, I realized that some of the steps had to be performed using the command line or were cumbersome and required additional steps when done through Visual Studio. This included:

• Setting up a local bonsai environment (necessary for debugging with the bonsai editor)
• Adding new bonsai operators like source/transform/sink
• Setting up the docfx website
• Specifying the package version for packing

In the end, I opted to sprinkle them throughout the existing article, but I am not sure if that is the right approach or if it clutters the article. One thing I also considered was whether it would be helpful to include a table of command-line commands at the end of the article, but I was unsure if it would be redundant.

Online Preview

[glopesdev]

@banchan86 thanks for taking a stab at this. I also struggled conceptually with the different options.

I feel these days the CLI is making a comeback, and perhaps it would not be so strange to simply replace all the visual steps entirely with command-line instructions.

One advantage is it makes things much easier to change as only text needs to be updated across versions. Also people can then feel free to choose between any editor they like.

I feel there are two targets here:

1. People who have done a few local extensions and now want to make their first reusable project to share with others.
2. People who are familiar with C#, VS, etc and just want to know which dependencies they need to install and how to structure their project and code so they can run it and debug in Bonsai.

For both 1. and 2. I feel we might not need the VS extensions

In the case of 1. they will likely be using VS Code already and we could guide them to creating a project there.

Also in the case of 2. it might be enough to point them at the dependencies and a template project.

Alternatively, we could also recommend the new Bonsai Package template, or have template snippets directly in the code as well for project items.

Anyway will review in more detail and investigate a few options.

[banchan86]

I agree with all the points you made, and I think replacing the Visual Studio steps and screenshots with just the command-line instructions might be better! I can go ahead and revise the article or sit on it for a while if you'd like to consider various options first.

[ablot]

Thanks a lot for the update. It clarified things a lot! What remained a bit confusing for me:

• the difference between bonsailib and bonsaipackage. The library seems to also be called "project" in this version of the documentation, which doesn't help to remember if a package contains multiple libraries or the other way round :)
• Is it normal that Bonsai.System is not included in the default csproj after running dotnet new bonsailib? The build fails without it (Bonsai could not be found in AssemblyInfo.cs)
• [probably minor] Even if I add Bonsai.System, I get a warning: AssemblyInfo.cs(6,60,6,64): warning CS8625: Cannot convert null literal to non-nullable reference type. Replacing the null with "" in AssemblyInfo removes the warning.
• What's the link between the docfx and the help poping up when we press F1 in the editor?

I'm clearly in the 1st user category and I don't think the visual studio part was helping much. It was great when everything worked but as soon as there is an issue I was lost as I had no clue which files contains which info. At least now I can look at the dry-run of the template to see what has been created and debug the issue.

[banchan86]

Hi @ablot, apologies for the delay in replying.

1. The way I understand it, bonsaipackage sets up the base infrastructure for either a single-project or multi-project bonsai package. If used by itself, the package will contain only a single project, but you can add multiple projects/libraries to the package by calling bonsailib. I think some of the confusion stemmed from trying to adapt the documentation when it used to be targeted at single-project packages, and also from trying to keep C# terminology. I will see how I can make the distinction clearer. So to recap:

   • bonsaipackage - basic bonsai package infrastructure
   • bonsailib - bonsai package project/library add-on

2. Hmm, you shouldn't need to include Bonsai.System as a package reference in the csproj, the "using Bonsai" in assemblyinfo.cs comes from Bonsai.Core, which is already included in the package reference. I was able to build/test/package the templates without having to modify or add any references. Could you detail the steps that led to this error? Did you make a new operator that relies on Bonsai.System?

   • your point made me realize, though, that we should add a section on how to add extra dependencies if people's custom operators need them, like the one in the scripting tutorial
   • Also discovered the bonsaivisualizer template needs Bonsai.Design, and also it doesn't show in the editor for some reason, need to investigate further

3. Ah, I also encountered this error. I think the null was left in there to make sure people gave their custom package a XML namespace prefix (like ephys for Bonsai.Ephys) for how Bonsai references the package in the .bonsai file. I did document that step, but I should also include a note for if people encounter that error.

4. Hmm, are you trying to understand more about the docfx integration? docfx automatically generates online documentation for dotnet projects, and as part of that, it generates an xrefmap (or a cross-reference map) to individual API pages for each member in the project (like Bonsai operators). We have integrated docfx's pipeline into the Bonsai Help functionality. When you press F1, it pulls the xrefmap and the link to the documentation for that operator. For that reason, and others (like being able to have workflow containers like the ones on the bonsai doc tutorials), we recommend using docfx as the documentation generator for bonsai packages. However, technically, you do not need to use docfx and can use other documentation generators; you will just lose that added functionality, as docfx is the one we are actively working with. Does that answer your question? Let me know if you meant something else.

Thanks for all the feedback by the way, I will see if I can address the points you raised in the next revision!

[glopesdev]

Ah, I also encountered this error. I think the null was left in there to make sure people gave their custom package a XML namespace prefix (like ephys for Bonsai.Ephys)

@banchan86 the null actually should work and I left it intentionally as a way to specify that no explicit prefix should be added.

I am very curious to learn under which conditions this one manifests (is it specific build settings?), as it might be a bug somewhere.

An empty string is probably valid too, so we could change the template to just have the empty string if easier.

[ablot]

@glopesdev I didn't get an error, just a warning CS8625. If I just do dotnet new bonsapackage, and dotnet build I get:

Restore complete (0.5s)
  test net472 succeeded with 1 warning(s) (0.3s) → artifacts\bin\test\debug_net472\test.dll
    [pathtodirectory]\test\src\test\Properties\AssemblyInfo.cs(6,53): warning CS8625: Cannot convert null literal to non-nullable reference type.

Build succeeded with 1 warning(s) in 1.1s

@banchan86 thanks for the reply. Regarding 2, the need for bonsai system, I don't manage to reproduce, so you must be right and I had a dependency in one of my transform that I had not noticed. My bet is that I got confused between dependencies of the .cs files that must be included in the .csproj to build and dependencies inside .bonsai workflows, which won't crash the build when they're missing, since they are needed only when opening the workflow in bonsai (if I understood correctly).