Ready and ready - we generate documentation from TypeScript code with Typedoc

In this article I will explain how we generate documentation from comments in TypeScript code. In general, everything is quite simple, if the requirements are simple. However, tune out for themselves is also not very difficult.

What we have - you can see here .

Code documentation is great!

When the task of creating documentation for our TypeScript API arose, the first thing we started with was just a label in google docs. We copied there the names of our components, their parameters, and the technical writer has already made documentation from this. It was terrible. The label was constantly becoming obsolete, it was inconvenient to copy into it, a lot of handmade work.

Then we nevertheless undertook to make the generation of documentation from the code, and I am extremely happy that we did it. Compared with the first approach, it’s just fantastic:

1. Documentation is always up to date and accurate. Even if the technical writer forgot to add the text - there will be something in the documentation.
2. Minimum manual labor. Time is spent only on writing the text - everything else is done automatically. No formatting, design and other routine.
3. The primary version of the documentation can be written by the developer, so there is no need to separately explain to the technician what is what. It simply edits the existing text.
4. All documentation is displayed in the IDE when using the API.
   
   

What it looks like

In the code, the documentation is of the following form:

/** * Register or update value for specified key. * @param key Key to identify value in container. * @param value Value to inject. * @returns Created or existing [DiRecord]{@link DiRecord} */ public register<KeyT, ValueT>(key: KeyT, value: ValueT): Typedin.DiRecord<KeyT, ValueT> { } 

To generate, first of all, you need to install typedoc. There are plugins for gulp and grunt .

 npm install typedoc -g 

The basic configuration can be seen on the example of my typedin library. It uses bare typedoc, without any problems and customization. You can generate such documentation for your project by simply adding one command to your scripts:

 typedoc --readme README.md --name typedin --out ./docs/ --tsconfig tsconfig.prod.json --excludePrivate --excludeNotExported --excludeExternals 

After that, a static site will appear in the docs folder, which you can, for example, publish via github pages .

It is worth noting that the documentation on using typedoc on the site and on github is usually irrelevant. For reference use:

 typedoc --help 

Comment syntax

In general, the syntax is from jsdoc. That is, comments are enclosed in /** */ and the @returns and @returns tags are used as in the example above (usually nothing more is required). The main difference from jsdoc is that you don’t need to write the type of the parameters, since it is already in the code.

Comments support markdown markup, which provides ample opportunities for formatting. I will not retell the entire syntax, I will give only the most frequent cases:

1. In order to separate one paragraph from another, you need to put an empty line between them

   
   

     /** *   - ,  . * *      ,  . */ function doSomething(){ } 

   
   

   Basically, you can use <br/> , but this is ugly.

   
   

2. To insert the example code, you need to indent 4 spaces + indents from the top and bottom

   
   

     /** *   [controlImpl]{@link controlImpl},     Pimpl. *       ref   render. : * * <MyControlImpl ref={this.attachControl} />; * * @param control    . */ protected attachControl(control) { this.controlImpl = control; } 

   
   

3. Bektik are used to insert the code directly in the text of the paragraph.

   
   

     /** *         *   ,    `new` (: `new MyControlParams()`) *      `this.state`. */ protected abstract createParams(): P; 

   
   

4. In the comments, you can refer to different parts of the API using the @link tag. Its syntax is similar to the usual markdown links :

   
   
   • [getParamValue]{@link BaseControlImpl.getParamValue} - link to a member of another class
   • [Constants]{@link Constants} - link to global object
   • [setParamValues]{@link setParamValues} - link to a member of the same class
   
   

Customization

The first thing we encountered was the need to customize the look. The standard theme did not suit us, we wanted to design in the company's corporate colors. In addition, in the standard theme, control controls in the upper part of the page do not work. All this is solved by creating your own theme, based on the standard.

Documentation states that all themes are inherited from the default theme. That is, we need to place in our theme only those files that we have changed. But it is easier to copy the entire topic entirely and already in it to understand what and how to fix it.

The theme consists of styles, scripts, various resources and handlebars patterns. Accordingly, in theory, changing the topic, you can do anything. If you need to add some complex logic to the templates, you can make a plugin. However, I didn’t succeed in doing something substantial in the handlebars templates. I have not worked with this template before, maybe this is the case. Therefore, I limited myself to modifying the styles, scripts, and non-essential edits in the templates.

To add my own style files and scripts, I placed the web-client.css and web-client.js files in the assets/css and assets/js folders, respectively, and wrote them in the layouts\default.hbs file:

 <link rel="stylesheet" href="{{relativeURL "assets/css/web-client.css"}}"> ... <script src="{{relativeURL "assets/js/web-client.js"}}"></script> 

In general, it turned out 70 lines of css and js. Thanks to css, our documentation has an original dark header , different from the standard one, and some other minor changes. In javascript, the "show protected / inherited" flags is mainly fixed. The HTML of these flags has also been fixed in the partials\header.hbs .

Total, to customize the generated documentation, you must:

1. Download the standard theme .
2. Add your css, js and fix templates.

3. Add the flag --theme < > when generating documentation:

   
   

   typedoc --theme MyThemeFolder --name typedin --readme README.md --out ./docs/ --tsconfig tsconfig.prod.json --excludePrivate --excludeNotExported --excludeExternals

   
   

So, by writing a simple css, js and a small template editing, you can solve most of the customization tasks. For more serious changes, you will need to deal with handlebars and write plugins.

Conclusion

Typedoc is still a rather crude project, and I was not able to find decent alternatives. Surprisingly, this theme is so underdeveloped, given that TypeScript is increasingly gaining popularity. I did not even manage to find a single adequate topic for typedoc - a search on github yields some results, but they are all non-working or do not represent anything interesting. This is despite the fact that the typedoc npm package has tens of thousands of downloads per day.

With this article I would like to draw the attention of the community to this topic and to typedoc in particular. The project is in dire need of contributors, it is necessary to develop the utility, write cool topics, update the documentation. Generating documentation from code is a mega useful thing and a good API Reference is greatly lacking in many javascript libraries.

It is safe to say that typedoc is a working tool that does its job and is flexible enough to satisfy most needs. We have a fairly large project, and we have not yet discovered any particular problems in its work. The code is parsed correctly, nothing falls and works well.

The only thing he lacks is the attention from the community. Use in your projects and share your work. Our theme can be downloaded on github .