Compodoc: One-Click Angular, Nest, and StencilJS Application Documentation

Compodoc-Documentation

The missing documentation tool for your Angular, Nest & Stencil application

https://github.com/compodoc/compodoc

Most of the Angular projects I have been part of have been huge with hundreds of components, dozens of modules, services, directives, pipes, and so on. As the application gets bigger and bigger, it sometimes becomes overwhelmingly difficult to keep track of things. When you’re working on codebases like these that show exponential growth in size over time, having a documentation tool within your app is incredibly important. The reason it’s important is that it increases the visibility of your application in these areas in particular:

  • It gives you a Bird’s Eye view of your application’s architecture.
  • It helps you keep track of your internal and external dependencies.
  • It helps you understand how different modules, components, services, etc. are connected to each other.
  • It gives you an overview of your documentation coverage.

I first started using Compodoc around 3 years ago in 2017 when it only supported creating documentation for Angular applications. It had me intrigued with the first use. I was positively shocked at how efficiently it turned my huge Angular application into detailed documentation. Since the first time I used it, it has only grown in popularity and also supports NestJS and StencilJS as of this writing.

What is Compodoc?

Documentation is always a boring task for developers who write software. When we have to write documentation for other developers, it is most of the time a source of frustration, and we rather prefer coding. Wouldn’t it be nice if there was a tool to automate documentation? That is exactly what Compodoc is. Compodoc is a documentation tool that helps you create documentation for your Angular, NestJS, and StencilJS applications with literally one click (of course, after you’ve installed it). It generates static documentation of your application which you can use yourself or share with your colleague or other stakeholders. The prime objective of Compodoc is to help developers by providing clear and helpful documentation of their applications.

Here’s a sample of Compodoc generation documentation in action:

Compodoc in action

Why should I use Compodoc?

Now that you have a fair bit of idea what Compodoc is, here are few reasons why you’d want to use Compodoc in your Angular, NestJS or StencilJS applications:

  • Compodoc supports Angular-CLI projects out of the box.
  •  Generates an automatic table of contents using elements found during files parsing
  • It is open-source and is available as an NPM package.
  • Compodoc is an offline tool. So, no server needed, no sources uploaded online.
  • JSDoc support: If you have code-comments in JSDoc format, Compodoc will also include those in the documentation
  • Documentation coverage – Generates documentation coverage report of your project.

Installation

Alright, I am convinced, how do I get it? Easy peasy! As I mentioned, it’s available on NPM so you can install it with NPM or Yarn.

You can either install it globally

npm install -g @compodoc/compodoc

or locally only for a specific project

npm install --save-dev @compodoc/compodoc

That’s it! that was easy, right? Hold that though until you actually use it.

Usage

I promised you a one-click documentation, didn’t I? So here we go.

Step 1:

compodoc -p tsconfig.json -s // If you installed globally

npx compodoc -p tsconfig.json -s //If you installed for a specific project
compodoc-generate-documentation
Generate documentation with Compodoc

That’s it! There’s no step 2. As you run this command, a new documentation/ directory will be created in your project root and you’ll notice some files in there as well. There! that’s your documentation in one click. The -s flag also starts an HTTP server on your machine and hosts the documentation which you can access by navigating to http://localhost:8080 in your browser.

Overview

As you open the documentation in your browser, you’ll see something like this:

Compodoc-Documentation-homepage
Compodoc Documentation homepage

The first page you see is either the README.MD file, if detected or the Overview page.

The overview page uses a great graph tool that gives a brief overview of how many modules and components you have in your application and how they’re connected to each other.

Compodoc Documentation- Application Overview
Compodoc Documentation- Application Overview

We can very clearly see what components are feeding into which module. If too many lines are randomly feeding into each other, then we know our app needs to be better organized. Also, if we have any components that do not feed into any modules, then we can clearly say that it is dead code, and should be deleted.

Deep Dive into Modules, Components, Services:

From the Overview page of the navigation menu, you can navigate to any modules, components, classes, services, interceptors, guards, interfaces, and “miscellaneous” within the app. This lays everything out there, so you know everything that’s going on within the app. It also defines all the things that we should see in our app. In particular, I like the sections for interceptors, guards, and interfaces. It can leave an impact on the team, that these are things that should be written.

Compodoc Documentation: Deep Dive Components
Compodoc Documentation: Deep Dive Components

Get Bird’s Eye view of your Routes:

Another cool feature of Compodoc is its ability to visualize all the routes that are in your application, and which components are attached. It also allows you to click through the routes and see which components are using a particular route.

Compodoc Documentation: Routes
Compodoc Documentation: Routes

Final Thoughts

Compodoc has become popular among developers in the past few years and I am sure many of you may have used it before as well. Nonetheless, I just hope that this article reaches to those who may not be aware. Compodoc is the documentation tool that I always recommend to my friends and colleagues time and time again.

I hope you enjoyed this article. If you already know about Compodoc, share this article for those who may not know. And if this was new for you, then you should definitely share. Because Sharing is Caring!

Be sure to follow us on the social media to get notified about the latest posts as soon as they’re published

Featured Image Credit: Photo by Kaleidico on Unsplash

Leave a comment

Your email address will not be published. Required fields are marked *