Restructure custom package docs and add controllers

[bpapaspyros]

Now that we have a controller template, we need to update the docs to also take users through the process of initializing a controller and explaining some of the fundamentals.

[bpapaspyros]

@eeberhard @domire8 I forgot to mention this effort during sprint planning. I've already opened a branch with some changes for controllers but soon after I realized I opened a can of worms there.

Perhaps we can have a short chat or you let me know here if you have clear ideas on how you would like this to be rewritten. I can continue on controllers, but it feels that if we change components I'll have to make symmetric changes, so planning comes first.

[eeberhard]

The can of worms being that we also want to be more comprehensive for components in general.

I would not necessarily rewrite things completely, but I think the writing a custom component page should instead be split into several pages. I would a section of pages where the modulo API for each interface is described in detail. E.g. Parameters, Signals, Predicates, Services, (eventually assignments). In many cases this modulo reference would apply equally for components and controllers. I would then add separate pages for a component vs a controller describing the core structure and key functions to override (constructor, step callback, lifecycle transitions for components, and for controllers the lifecycle and update function).

Describing a component should be updated to the unified extensions schema - so it could stay a single page.

Most generally, creating a custom package and building a component package of course needs updating in general with the new template changes and to make the naming more consistent for extension packages, which I think is independent of the changes to the API reference.

Based on that, I think you can split up the work reasonably well, though of course it will be many steps in total.

[bpapaspyros]

The can of worms being that we also want to be more comprehensive for components in general.

Yup

I would not necessarily rewrite things completely, but I think the writing a custom component page should instead be split into several pages. I would a section of pages where the modulo API for each interface is described in detail. E.g. Parameters, Signals, Predicates, Services, (eventually assignments). In many cases this modulo reference would apply equally for components and controllers. I would then add separate pages for a component vs a controller describing the core structure and key functions to override (constructor, step callback, lifecycle transitions for components, and for controllers the lifecycle and update function).

Describing a component should be updated to the unified extensions schema - so it could stay a single page.

Most generally, creating a custom package and building a component package of course needs updating in general with the new template changes and to make the naming more consistent for extension packages, which I think is independent of the changes to the API reference.

Based on that, I think you can split up the work reasonably well, though of course it will be many steps in total.

Ok, I'll push on that front and start a staging branch with some changes over there.