DCM notes for 2024-12-30

[banchan86]

Documentation

• Add API template docfx-tools#9
• Add API TOC categories template docfx-tools#7
• Documentation for Bonsai.Scripting.Expressions docs#112

[banchan86]

Feedback on bonsai-rx/docfx-tools#9:

• @RoboDoig wanted clarity on what we were planning to have in the top level workflow container. Just the operator itself or a minimal working configuration. Important for there to be consistency. @glopesdev Goal was to have a visually recognisable element for people to recognise the node, copy and paste into their workflow, and troubleshoot doc issues with the nodes being exported. I think we settled on just having the node for consistency as even in the case of a minimal working configuration it would be hard to define for all packages.
• @glopesdev wanted to emphasize that reference documentation should be complete and people should be able to find what they need if they want to go to that level. We just want to ease the transition for people by removing some of the clutter and flattening the hierarchy of information.
  • The input/output layout might not work for classes with lots of overloads.
  • We can still separate out the input/output methods from the rest, but the other methods should still be listed in a separate table.
  • Inherited members need to be processed and not just be excluded. For example some operators have helper methods that can be used from regular C# code like the spinnaker sources. They are not useful necessarily from a naive user, but they need to be listed for who wants to extend them.
  • Inherited Members properties that show up in the Bonsai property grid should be listed (@banchan86 note: this should already be done, try out the API template on the 'MatrixWriter' node.)
• @jfrazao Try a table format for the input/output layout (@glopesdev has made a mockup before).

Feedback on bonsai-rx/docfx-tools#7:

• @glopesdev Grouping them by Bonsai types might not be necessary, maybe just group all operators together, enums and classes.

Feedback on bonsai-rx/docs#112:

• @glopesdev The expression language page on dynamic-linq might be the best reference we have for now on the underlying expression language, but some things on there might not work as we are using an older version of dynamic-linq.
  • Option 1 - make a Note alert that tells people that the version we are using is older and some expressions might not work.
  • Option 2 - Adapt the operator table in that link by trying out the different expressions and maybe also change the descriptions
• @jfrazao There are some more expressions/methods for type conversion that can be added, can also add a link to the type section on the expression language page or a table listing the different types that are supported.