Generating Documentation for Angular 2 apps and NativeScript

Published in

Falafel Software

4 min readNov 28, 2016

Abstract

Static documentation generators are abundant on the web. Whether you are working on a complex web application or simply an API project, you will find a tool for your support.

With complex JavaScript applications, we have used a variety of tools including the infamous JSDoc and Docco. These tools have been serving us well until we started developing a complex Angular 2 application and we desired to have a solid documentation tool added to our toolbelt.

In this column, I am going to present some of the options that you have for generating static documentation for an Angular 2 application. For this purpose, I’ve selected John Papa’s Tour of Heroes Angular 2 application.

TypeDoc

TypeDoc is the most popular documentation generation tool for TypeScript projects. It can parse *.ts files and understands TypeScript specific elements such as Classes, Enumerations, and Types. The generator runs the TypeScript compiler and extracts the type information from the generated compiler symbols. Unlike JSDoc, including additional metadata in the code comments is optional. If you want to understand the difference between JSDoc and TypeDoc, you can look at this article. TypeDoc is adequately configurable and has built-in themes. TypeDoc plays nicely with Webpack, Gulp, and Grunt, so it will fit the majority of workflows.

Since the Tour of Heroes Angular 2 application is written in TypeScript, then TypeDoc comes as a natural fit for documentation generation.

To setup TypeDoc in our Tour of Heroes application we install the package globally which is the preferred way of doing it:

$ npm install -g typedoc

And then a local install for the application:

$ npm install --save-dev typedoc

In our package.json, we need to add the documentation generation scripts such as:

"scripts": {
    ...
    "docs": "npm run typedoc -- --options typedoc.json --exclude '**/*.spec.ts' ./app/",
    "typedoc": "typedoc",
    ...
  }

The typedoc.json file includes all the configuration options for TypeDoc, so we need to add it to our project:

{
  "mode": "modules",
  "out": "docs",
  "theme": "default",
  "ignoreCompilerErrors": "true",
  "experimentalDecorators": "true",
  "emitDecoratorMetadata": "true",
  "target": "ES5",
  "moduleResolution": "node",
  "preserveConstEnums": "true",
  "stripInternal": "true",
  "suppressExcessPropertyErrors": "true",
  "suppressImplicitAnyIndexErrors": "true",
  "module": "commonjs"
}

Here we specify that we want the documentation to be generated in the docs folder and use the default theme. We also specify the output mode of the project, target, and other configuration options. You can read more about it here.

The generated documentation looks as follows:

Compodoc

Compodoc is regarded as “the missing documentation tool for your Angular2 application”. It generates simple yet elegant HTML documentation. It supports markdown and automatically creates a table of content. Unlike TypeDoc which is for any TypeScript application, Compodoc is built for Angular 2. That is why Compodoc provides graphical elements such as a hierarchical graph of each module to effortlessly conceptualize its dependencies. Compodoc is now the documentation tool of choice for Angular Seed and Angular Seed Advanced.

Configuring Compodoc for the Tour of Heroes application is a breeze. We install the package locally:

$ npm install --save-dev compodoc

Add our scripts for generating and serving the documentation:

"scripts": {
    ...
    "docs": "node_modules/.bin/compodoc -p tsconfig.json -d docs",
    "serve-docs": "node_modules/.bin/compodoc -s -d docs",
    ...
  }

Generate the docs:

$ npm run docs

Serve the generated documentation:

$ npm run serve-docs

And the result looks pretty impressive:

You can further customize the generated documentation as indicated here.

NativeScript apps written in Angular 2?

If you are using Angular 2 with your NativeScript applications then Compodoc can be used to generate your api documentation. The setup is almost identical to any other Angular 2 application, except that you need to exclude your documentation folder from the build or place it outside of the source of the application.

For demonstration purposes, I will use the Sample Groceries application. My NPM scripts look as follows:

"scripts": {
    "tslint": "tslint \"app/**/*.ts\"",
    "docs": "node_modules/.bin/compodoc -p tsconfig.json -d ../docs/",
    "serve-docs": "node_modules/.bin/compodoc -s -d ../docs/"
  }

The documentation will be generated outside of the NativeScript project as you can see in this fork. The result looks like the following:

Bonus

AngularDoc, as stated on the site, provides “architectural analysis and visualization for Angular 2 projects”. To get started you will need your Github account, so the service can scan your desired repo. I haven’t tried the service yet, but it looks very impressive looking at the showcases. I did try however the Visual Studio Extension which I recommend installing if you are working on a complex Angular 2 application.

Conclusion

We have seen a few of the options you have to generate documentation for an Angular 2 application. There are definitely other tools in the marketplace, so I’d love to hear from you what your preferred choice is.

Get the code

Originally published at Falafel Software Blog.