Compodoc — Documentation tool for Angular applications
Documentation is always a boring task for developers who write softwares. When we have to write documentation for other developers, it is most of the time a source of frustration, and we rather prefer coding.
I work at a French IT services company, and we have to provide such documentation for our customers. We usually deal with two scenarios :
- Documentation written using Microsoft Word, with a “functional” look, and sometimes API inside. The targets are people who are not developers, but managers.
- Generated documentation, like API documentation, for backend and/or frontend softwares.
Since we are developers, we are by nature, “ lazy ” people, trying most of the time to code a task, rather than executing it. And “generated” documentation is a good solution.
The other advantage, is “ living ” documentation. As software grows, and code is being documented, the documentation automatically syncs with the last updates.
For AngularJS developers, the de-facto solution for generating documentation is a tool called “ Dgeni ”, created by the AngularJS team. It is a very low level tool, and works fine with a little of configuration and a couple of scripts.
We started the switch to Angular a few months ago in my company, and the question about “ Documentation ” tooling came up exactly last month.
After some researches on the Web, I found out that there were no tools available, so the conclusion was straightforward : “ Let’s code one ”.
It was the start of the Compodoc project.
What’s is Compodoc ?
Compodoc is a documentation tool for your Angular application.
The goal of the tool is to generate a documentation for all the common APIs of Angular : modules, components, injectables, routes, directives, pipes and classical classes.
Give me an example
The workflow is easy. I am using this Angular demo project for the screenshots below :
- install it with npm :
npm i -g @compodoc/compodoc- run it inside the folder of your Angular 2 application
compodoc -p src/tsconfig.json
After some logs in the console, you got the generated documentation in the ./documentation/ folder at the root of your project folder.
You can then run an HTTP server in that folder, or launch the previous command with the -s flag, and the tool will serve you the documentation, by default on http://localhost:8080
The home page is generated using the README.md file if detected, and instead the overview page.
The overview page uses a great graph tool developped by Wassim Chegham called angular2-dependencies-graph; and give a brief overview of how many modules and components you have in your application.
Now let’s see a page for one module, the TodoModule for example. You will have the local dependencies graph for this one, and the list of declarations, imports, exports, etc of your module.
Let’s go even further with a component page, the HeaderComponent. As in the module page, you have all the “@component” decorator options listed, if available for this component. The @inputs and @outputs are also available.
And it is the same thing for classes, directives, pipes and services. The TodoStore is a good example :
Which comments did i have to write for getting these results ?
Just normal comments. We have added support of markdown syntax with a npm package called “marked”. We are thinking about a feature for linking comments like normal markdown links. Stay tuned.
What’s next ?
The tool is just a few days old, so we will try to test it on as many projects as we can in order to improve it and optimize it.
We plan to add an option to provide external “functional documentation”, like markdown files in a folder, and add them to the generated documentation, in a dedicated entry in the left-side menu bar.
We will also try to do the same stuff for AngularJS 1.5+ projects, build using Typescript.
We appreciate your feedbacks. Please open any issue you may encounters and pull-requests are more than welcome.
Follow Vincent Ogloblinsky / @vogloblinsky for getting updates.
