Monday, September 3, 2018

Beginner Guide to typedoc- Typescript Documentation API generator

typedoc tutorials

TypeDoc is a  Documentation API Generator for generating documentation for typescript applications. This is similar to JSDoc, ESdoc, and JavaDoc.
Documentation for any project is one of the key factors for successful application development.Type doc tool takes typescript files or typescript project as a input, parse it and generates Documentation in a different format as output. HTML is one of the generated formats which contains, Links, Styles, and HTML of code.
This will be generated by reading typescript code elements like classes, interfaces and methods.

Install and Setup 

Type doc can be used as standalone NPM command line or can integrate with a webpack gulp and grunt tools Before installation of typedoc, First nodejs need to installs and npm and node command should run successfully You can install it either globally or locally. -g option will installs globally, without -g option and --save-dev option installs locally

npm install -g typedoc
This installs globally and typedoc command will be available

B:\Workspace\blog>typedoc --version
TypeDoc 0.12.0
Using TypeScript 3.0.3 from C:\Users\Kiran\AppData\Roaming\npm\node_modules\typedoc\node_modules\typescript\lib
And also you can configure typedoc command and run as npm command using below configuration Add below entry in package.json


"scripts":{
   "tdocs":"npm run typedocs [options] "
}
Once the configuration is added, you can run via npm command "npm tdocs"

typedoc Options 

Options are provided with typedoc command are a double hyphen(--)
Option description
out It is output Directory to which documentation generated for it.
model Output mode of the compiled project ie file or modules
theme Specify theme for Generated documentation template, can be the default, minimal, or path to the custom theme
target Configure EcmaScript js versions ES5, ES6 that need to compile with it
include It included all files for generation
exclude Excluding all files for generations

Example 

We will see how we will generate a documentation for Typescript file.. First Create typescript file - Animal.ts

 class Animal {

        public nonveg:boolean;

        constructor() {
            console.log("new animal created");
        }
 eat():void{
   console.log("new animal Eat method");

 }

    }
 class Lion extends Animal {

        constructor() {
            super();
            this.nonveg = true;
        }
 eat():void{
   console.log("Lion Eat method");

 }

    }
 class Cat extends Animal {

        constructor() {
            super();
            this.nonveg = true;
        }
 eat():void{
   console.log("Cat Eat method");

 }

}

Generate Html Documentation

Using typedoc command, please issue the  command
typedoc --out docs .

And the output generated documentation is below screenshot typescript documentation generator TypeDoc configuration changes

 Typedoc comes with tdconfig.json files which contain configuration options required to generate documentation. This files contains typescript compiler options and include which files are included to generate Documentation Exclude option is exclude the files for generations.
typedoc configuration typeconfig.json

Typedoc bundler plugins

 Typedoc can be also used with javascript build tools. There are already plugins npm packages available.

  • Grunt - grunt-typedoc
  • Gulp - gulp-typedoc 
  • Webpack - typedoc-webpack-plugin
I will post examples for this plugins in future posts.

Related article


EmoticonEmoticon