Add to Schematics API documentation

[cafesanu]

📚 Docs or angular.io bug report

Description

Hello. I just spend some time creating my first schematics. Have to say it's awesome! Unfortunately, I had to spend much of my time reading throughout the angular @schematics code to see examples of how it works and articles on Medium by other people about how to create a basic schematic.

It would be awesome if the Angular team spends some time making an awesome documentation of such an awesome feature! This has so much potential to be wildly used, and I'm afraid that without proper documentation, it won't reach the masses!

Just try to google a simple example of How to copy a file in angular schematics, and there is no simple link to it. I ended up reading a file via the tree.read into a buffer, transforming the file into a string, and then creating a new one via tree.create, but don't even know if this is standard or not 🤷‍♀️

In any case, I love schematics, but there is no official documentation at all other than two blog post (one with unit test) with simple examples you guys created in the Angular Medium Blog.

Thanks! Nice job!

[Airblader]

Having recently dealt with this to implement a default "ng add" schematic to automatically import a module etc, I fully agree with this request. Schematics are awesome, but the experience of working with them was really poor and ultimately left me with a feeling of not having done things in the intended way because it felt just too awkward.

[ericmartinezr]

See #28343. Now you can see the PR and provide some feedback :D

[cafesanu]

Wow nice! I will definitely take a look this week. Any Eta for release? Thanks!

[jenniferfell]

@cafesanu : I'm sorry, I can't provide a specific ETA. "Soon." The doc has been through several rounds of technical updates and review with subject matter experts, and we are now waiting on codeowner approval. Sometimes the codeowner review is quick, but sometimes the codeowner wants updates for accuracy, completeness, or clarity.

As you noted on that PR, there is more than can be said about schematics, so we are hoping to get approval based on accuracy and clarity, merge, and then follow on with subsequent updates for completeness. (doc is never done)

Are you asking for timeline because you'd like to start working on a derivative update? I'll let codeowner know that there is work that will be easier when that PR lands.

[Splaktar]

This was also being tracked in angular/angular-cli#12149.

[Splaktar]

I just wanted to link to @cafesanu's long post about additional details that need to be added in the future. It's hidden by GitHub (with 115 other comments) by default. Find it here: #28343 (comment)

I also have a Google Doc with a full outline of the structure of what needs to be documented for Schematics. I'll try to go and review it to make a list of what's missing after PR #28343 lands.

[cafesanu]

Adding my original comment here so it's easier to see @jbogarthyde

...from #28343 (comment):

Sorry to be so repetitive and not trying to be a pain. I truly appreciate the great work that is being put into this. So let me put just a general sentiment that generalizes all my previous comments.

I feel like schematics has so many libraries/utilities that are reusable and so many utilities that deserve themselves some documentation with examples on how to use them without having to dig into the code, like this one for example https://github.com/angular/angular-cli/blob/master/packages/angular_devkit/schematics/src/rules/base.ts

Also, I ended up using for my own schematic that modifies json files the util in here https://github.com/angular/angular-cli/blob/master/packages/schematics/angular/utility/json-utils.ts

I ended up using appendPropertyInAstObject, findPropertyInAstObject, and insertPropertyInAstObjectInOrder.

So what I'm trying to say is that schematics tutorial should somehow include documentation for all that awesome util libraries and whatever the team wrote to be reusable and agnostic.

Some examples that come to mind about writing either example of documentation on the libraries that I have had to dig into the code to understand (And I'm sure there are many more that I do not know about) are :

• How and when to use Tree Create, Rename, Overwrite, and Delete
• How to use the json utility
• What is a JsonAST and how to work with them
• How to modify a TS file (like adding an import or adding a component to the declarations array within and Angular module
• are there utils to traverse a TS file
• Loading files to a buffer
• explaining the logger in https://github.com/angular/angular-cli/tree/master/packages/angular_devkit/core/src/logger
• What is this json parser https://github.com/angular/angular-cli/blob/master/packages/angular_devkit/core/src/json/parser.ts
• Basically explain what each of the libraries in here do (https://github.com/angular/angular-cli/tree/master/packages/angular_devkit/core/src), and anywhere else that I might not know about

Basically in the few days that I have been learning schematics, I have had to dig into the code and see example on how your added stuff to a json, how you copy a file, how you delete a file, how to chain schematics, etc.

The way I see schematics is as a framework within a framework that deserves documentation and example on how to use is beyond the hello world basic example.

Thanks again for your awesome work! love schematics!

[jbogarthyde]

Renaming this issue - the new basic Schematics Guide landed, but this issue has good suggestions for topics that should be added to provide Schematics API documentation.

Both Architect and Schematics need API doc

1. Teams need to determine what is public
2. We need to figure out where to put it, and how to generate it.
3. Then we can document the public API

Related Issue: #30575

[Splaktar]

We should add docs on CLI prompt authoring in schematics based on https://github.com/angular/angular-cli/blob/master/docs/specifications/schematic-prompts.md.
(re: https://twitter.com/tim_deschryver/status/1169550006027730945?s=19)

[SchnWalter]

Before publishing the API, there needs to be a round of cleanup, see: angular/angular-cli#17597

[kapunahelewong]

Status: docs team will need to assess the available material (above) and incorporate what's missing into the doc. The second step will be to uncover the questions that remain after adding the additional info and work with an engineer to make sure all the topics are covered.

[angular-robot]

Just a heads up that we kicked off a community voting process for your feature request. There are 20 days until the voting process ends.

Find more details about Angular's feature request process in our documentation.

[angular-robot]

Thank you for submitting your feature request! Looks like during the polling process it didn't collect a sufficient number of votes to move to the next stage.

We want to keep Angular rich and ergonomic and at the same time be mindful about its scope and learning journey. If you think your request could live outside Angular's scope, we'd encourage you to collaborate with the community on publishing it as an open source package.

You can find more details about the feature request process in our documentation.