search

angular / angular-cli

CLI tool for Angular
https://cli.angular.dev
MIT License
26.79k stars 11.98k forks source link

Generate documentation for default builders #23088

Open dgp1130 opened 2 years ago

dgp1130 commented 2 years ago

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 commented 1 year ago

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

dgp1130 commented 1 year ago

@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 commented 1 year ago

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

alan-agius4 commented 1 year ago

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 commented 3 months ago

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 commented 3 months ago

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

YuliaGaliulina commented 2 months ago

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