Create API pages for components

[fateeand]

Tasks

Beta Give feedback

1. Create a JSON generator (to generate json files from ts annotations) #300
   composition enhancement +2
   
2. Update the docs app to consume generated json files #301
   composition enhancement +2
   
3. Annotate inputs and outputs of the components #193
   composition enhancement +2
   
4. Define types and configs in docs #320
   composition enhancement +2
   
5. Retrieve annotations for setter input params #328
   bug composition +2
   
6. Retrieve default values for the Input properties defined using setters/getters #337
   composition enhancement +2
   
7. Remove internal entities from the documentation page #349
   bug composition +2
   
8. Support advanced types in docs #350
   composition enhancement +2
   
9. Show description of service method parameters #355
   composition enhancement +2
   
10. Support enums #362
    0 of 3
    composition enhancement +2
    

[lukasmatta]

I did a little research on how are two popular UI libraries taking care of their docs generation. Here is the summary:

PrimeNg

Basically, all the logic for API docs generation is inside the build-apidoc.ts file. It uses the TypeDoc tool. The tool is able to iterate over all modules (and for each module over all components) and extract the code docs. Then they use this to generate one JSON file containing API data for all the components.

That JSON file is simply imported in the AppDocApiSection component and the data for currently opened module is loaded from the file (this means that the whole JSON file will become part of final js chunks).

It might be a bit inefficient, one has to load data for all the components even though he might be interested only in one component. The size of the JSON file is 1.12 MB, around 500 kB minified and around 60 kB when transferred gzipped (not that bad considering it contains all the components API info).

I think we might get inspiration from the build-apidoc.ts file and use similar solution for our project.

Angular Material

Angular Material team is using tool Dgeni, but as this tool is intended to be used with AngularJS, they are using modified version of it. They basically use it to export API docs into the separate repo in the form of HTML pages.

Their modified version of Dgeni is quite coupled with the build tool Bazel. Some discussion regarding the Dgeni usage with Angular2+ projects is going on in this issue.

DocViewer component is then used to dynamically load those HTML pages into to the appropriate positions in the docs page.

---

To conclude, I find Angular solution to be more scalable and performant, but also more complex. For now, I'd go the PrimeNg way.

// Edit:
I also looked for some tool to be used, e.g. Storybook or something similar. But I find Storybook to be too complex for us, at least for now. Ng-doc is more about converting MD files to docs, not really about generating API docs.