Compodoc Integration in Angular App
What is Compodoc?
Compodoc is a very useful library on npmjs which can be used to generate documentation on the after each and every change in the product. Unlike most documentations which are boring to read and hard to understand, this library creates a very developer friendly static website which can be used as reference by everyone including people with little to no technical understanding of the underlying codebase. It can be used to understand the structure of the application and gives an overhead view of the application which can be very helpful when a new developer joins the team or upper management wants to take a look at it and suggest ways to optimize the code.
How long does it take to setup?
Well, start your stopwatch and I guarantee you that it won’t take more than 15mins to set it up in your local.
How to set it up?
- Just go to your Angular application and type the following in your console.
npm install -g @compodoc/compodoc
This will install compodoc globally in your machine and can be used in multiple projects without hassle. Alright, only two more steps to go —
2. Create a file named
tsconfig.doc.json, containing a key
include pointing to
src folder and you can also add items to the
exclude key so as to control what you want to expose in the documentation. It is as simple as writing the two lines below.
"exclude": ["src/test.ts", "src/**/*.spec.ts", "src/app/file-to-exclude.ts"]
3. Now just go to your package.json and the following scripts.
"compodoc:build-and-serve": "compodoc -p tsconfig.doc.json -s --hideGenerator -o",}
And its DONE. You have successfully completed integration of compodoc library into your project. Now its time to see the magic. As soon as you run the above command using:
npm run compodoc:build-and-serve
It will open a new tab on the browser and you can see the website with all the information you need about the project. It will on run in local and can easily be deployed as a static website using github pages or on blob storage(Azure).
Let’s roll up the curtain and look at the doc:
It is highly intuitive and you can checkout the structure and code by just navigating on the left section of the page. It generates beautiful charts for better understanding.
You can even access the source-code by switching tabs. You can access much more from the left tab.
What’s the use of the documentation if it cannot be shared?
It can be easily shared and deployed as a static website anywhere you want by just using the auto-generated files in the /documentation folder. (similar to /dist folder)
There are a lot more customizations that you can perform over this to suit your theme and preferences. Check out the official documentation for it.
Time to try it yourself and leave comments if you found this article helpful. I really feel integrating this library into your application can improve the workflow and discussions in your team. I hope you liked this article and stay tuned for an interesting topic I have planned for the next one.