I recently posted Dynamics Portals Script Libraries that outlines a new GitHub repository for Portals TypeScript libraries. I’ve added a few pages to the repository Wiki with instructions on how to setup, but I wanted to include information on the modules and methods themselves as well.

Luckily, we have TypeDoc!

TypeDoc

“A documentation generator for TypeScript projects”

For quite a few years, developers have had tools for generating SDK style documentation for their code libraries. NDoc and Sandcastle are two tools that I’ve used on past .NET custom development projects. These both converted XML code comments into a variety of formats, such as web pages or CHM files.

TypeScript’s comment markup offers a very helpful method for including intellisense, so I do my best to document my TypeScript as thoroughly as possible. It’s helpful for myself while building new modules and others on team projects who might reference my code. TypeDoc converts these comments into navigable web pages similar to NDoc. The tool includes comment details from TypeScript namespaces, modules, classes, and methods, converted into a self contained set of HTML pages.

So we can document our code once and make it available inline as intellisense and as an easy to read index for those new to your TypeScript libraries.

Installation and execution

TypeDoc is a Node module that you can install locally or as part of your build process. Setup is fairly straightforward, even for a Node novice like myself. I followed the instructions for a Local Installation. The first step was installing Nodejs from https://nodejs.org/ and then a simple matter of following the command line steps under the Arguments section. I chose the minimal theme and placed the generated documents under the repository at the root under the creatively named folder docs. The command line is as simple as pointing the tool to a source code folder with some additional parameters:

typedoc --name "Dynamics Portals Scripts" --mode file --theme minimal 
  --out docs ./DynamicsPortalScripts/scripts

When you execute the ‘typedoc’ command, the TypeScript is actually compiled, so you will see any open errors in your script library, which is pretty handy instead of just skipping issues. Once the generation is complete, you will see an index.html at the root of the output folder. in my case, I have docs/index.html.

When you navigate to the generated index.html in GitHub, you understandably see the raw HTML. We are looking at a code repository, so that makes sense! You can download the docs folder and browse locally, but I really hoped to have links right from my repository.

htmlpreview.github.io

Fortunately, GitHub user niutech created a very cool utility called http://htmlpreview.github.io. Pass it a URL to your HTML files in GitHub and it renders the page for you. So now I can post a link on my repository README page that allows us to browse the documents online. I think it’s a very cool idea and it works great for this type of project.

Check it out at the following link:
https://htmlpreview.github.io/?https://raw.githubusercontent.com/jamesnovak/DynamicsPortalScripts/master/docs/index.html

The Dynamics Portals Scripts repository is fairly small compared to some projects but this kind of documentation is very handy when posting usage documentation with the repository. So just imagine how helpful it can be for large scale projects with hundreds of source files and even more modules, classes, and methods!

I am continuing to update the comments and I have moved a few things around within the library, so keep an eye out for updates and more documentation and examples!