Generate documentation for default builders

[dgp1130]

AIO has a page on angular.json workspace configuration which lists default builders. Unfortunately these builders link directly to the JSON schema, which is not very intuitive.

We should process these schema files and generate a page for each builder linked from the workspace configuration. This would make it much easier to understand @angular-devkit/build-angular and related builders' options.

[sumitparakh]

@dgp1130 @alan-agius4 Can I take this up?

[dgp1130]

@sumitparakh I'd definitely love to see this happen. I think it will be particularly relevant for Jest and Web Test Runner support, and having dedicated pages for those builders would allow us to decouple the existing ng build / ng test documentation from their builders (ng test docs currently assume you're running Karma, which won't always be true as we roll out Jest and WTR).

This probably requires some cross-repo work since angular.io is hosted in the angular/angular repo. I'm also not too familiar with how doc generation is currently implemented, so it probably isn't the best issue for a community contribution, but if you're motivated to make it happen I'm happy to help out where I can.

I think the scope here is to generate a page based on the schema.json files for each builder just like we currently do for CLI commands (ex. ng build). Then get those pages into angular.io. There's a process for importing CLI schema content into angular.io, but I'm not familiar with how it works offhand. Might take some digging and asking around to figure out the specifics.

[sumitparakh]

Thank you so much @dgp1130. I will try to figure it out and generate the docs accordingly.

[alan-agius4]

Myself and @devversion are probably the most knowledgeable persons of the above mentioned process. However, I will be OOO starting from next week for 4 weeks.

[YuliaGaliulina]

I'm not sure if any of the discussion participants got their hands on the suggested implementation but I have created a dedicated resource that does exactly what @dgp1130 proposed. The documentation is dynamically generated from builder schemas and as of now supports Angular versions 12 through 18. Basically it's schemas that are rendered in a more user friendly way with an ability to switch between versions: https://yuliagaliulina.github.io/angular-cli-builders/

I would love to hear feedback from @alan-agius4 and @devversion !

[alan-agius4]

Hey @YuliaGaliulina, that’s really impressive. Well done!

[YuliaGaliulina]

@alan-agius4 I'm glad to hear that, thanks! Do you have any suggestions on how to improve the documentation?