Custom API template to improve documentation user-friendliness

[banchan86]

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 bonsai-rx/docs#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

• Make a API docs converter that supports additional languages. Theres not much information on it though and it seems overly complicated. The best I can find as a starting point is to look at how they supported the [.Rest API].(https://github.com/dotnet/docfx/tree/f69055285edc3a72d97e5db8cb39d4744ffc0ba8/src/Docfx.Build.RestApi)
• Make a document processor - there is more information on this at Schema Document Processor and a tutorial on how to Create a Plugin.

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 Categorise API nodes in Table of Contents #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.