The current API section for Bonsai package documentation is very C# developer centric and not as intuitive for Bonsai end users to navigate/learn from. Recently the Open Ephys Team in the process of setting up the documentation for their newest library has revamped the documentation template to target end users and implemented many features which we think would be useful. At the same time we would like to be somewhat conservative and still try to target a broader audience by retaining some bits and pieces which we think would be helpful for advanced users or developers. We have discussed this previously at https://github.com/orgs/bonsai-rx/discussions/1851 and https://github.com/bonsai-rx/docs/issues/85.
Proposed Solution
Starting from the template that was made by the Open Ephys team for the Bonsai-Onix1 website, I modified it so that it could be imported as a template within the docfx-tools submodule. In the process, I removed any Open-ephys specific package code, and added code to account for edge cases that were not present (for instance, Transform operators are not present in that library).
The features that were retained from that template:
Remove declaration blocks which did not add much meaningful information.
Display properties and Enums members in tabular format for legibility.
Display Enum members within Class property tables for easier access.
Hide auxillary methods
Add inherited members properties to classes (this more closely reflects what users might see in the Bonsai UI)
Special layout page for Bonsai Operators -
Add Operator workflow container for Bonsai Operators
Add Operator Class (Source, Sinks, etc) in title
Highlight Input and Output methods (Process(), Generate()) - are there others?) for Bonsai operators with a Flowchart
On top of that, I added these features
Add back namespace and assembly information
Add back class relationships (inheritance, implements, derived members) but strip inherited members
Surface links to Bonsai documentation on operators and observables - this might be a good way to herd users who might not know of the general Bonsai docs to explore that website.
Alternative Solutions
Docfx supports Bootstrap containers, which can be used to divide up the content into tabs. We could include the input/outputs as the default content for all the pages, but add these sections below that. This might be a good way to reduce information overload on the main page but still make the content available to advanced users (and avoid oversimplifying the content).
Additional issues
C# specific information We should also discuss what we would want to keep, currently for some classes/operators there were no information left behind in the original template.
Accessory methods and constructors have been removed from the template, but we should discuss if we would want to add them back in, for instance Configure() for configuration classes is currently hidden
The inheritance tree wasn't present in the orignal template, I had added them back in but stripped out the inherited members as I received feedback that it added in a lot of noise.
The raw code snippets that preceded each item was stripped as I also received feedback that it did not add much information.
IncludeWorkflows - The big one, what to do which IncludeWorkflows which are a major component of packages such as Bonvision. With this template, as long as we can generate YamlManagedReference files from .bonsai files, we can package them into the API documentation. As far as I can tell, there are two methods
Both of these methods, I think I am going to need some help with as it requires C# dev knowledge.
Supplementary Solutions
The TOC template https://github.com/bonsai-rx/docfx-tools/issues/6 can also be used to sort API classes and hide accessory classes, and together with this template will help improve user-friendliness of the docs.
Motivation
The current API section for Bonsai package documentation is very C# developer centric and not as intuitive for Bonsai end users to navigate/learn from. Recently the Open Ephys Team in the process of setting up the documentation for their newest library has revamped the documentation template to target end users and implemented many features which we think would be useful. At the same time we would like to be somewhat conservative and still try to target a broader audience by retaining some bits and pieces which we think would be helpful for advanced users or developers. We have discussed this previously at https://github.com/orgs/bonsai-rx/discussions/1851 and https://github.com/bonsai-rx/docs/issues/85.
Proposed Solution
Starting from the template that was made by the Open Ephys team for the Bonsai-Onix1 website, I modified it so that it could be imported as a template within the docfx-tools submodule. In the process, I removed any Open-ephys specific package code, and added code to account for edge cases that were not present (for instance, Transform operators are not present in that library).
The features that were retained from that template:
On top of that, I added these features
Alternative Solutions
Docfx supports Bootstrap containers, which can be used to divide up the content into tabs. We could include the input/outputs as the default content for all the pages, but add these sections below that. This might be a good way to reduce information overload on the main page but still make the content available to advanced users (and avoid oversimplifying the content).
Additional issues
C# specific information We should also discuss what we would want to keep, currently for some classes/operators there were no information left behind in the original template.
IncludeWorkflows - The big one, what to do which
IncludeWorkflowswhich are a major component of packages such as Bonvision. With this template, as long as we can generate YamlManagedReference files from .bonsai files, we can package them into the API documentation. As far as I can tell, there are two methodsBoth of these methods, I think I am going to need some help with as it requires C# dev knowledge.
Supplementary Solutions