Publishing API reference for your TypeScript project with TSDoc

Problem

Let's suppose you have a frontend project with TypeScript as a basic programming language and you want to publish the API reference of all components, classes and functions in your project on the web - to share with your co-workers or customers (especially if this project is some kind of the code library).

Solution

Here is where Aistdoc console utility with Aistant documentation service come to help. With Aistdoc you can generate the full reference of your TypeScript modules and then publish them under your Aistant account (even with a free subscription plan). Here are the detailed step-by-step instructions how to do it:

Step 1. Installation

First of all we need to install all necessary components:

1. Node.js

In this scenario we will use TypeDoc which is installed via NPM, so you need Node.js with NPM installed first.

2. TypeDoc

TypeDoc tool allows you to parse your TypeScript code with TSDoc comments and generate JSON files with the full API reference of your library. After that those generated files will be passed to AistDoc for publishing. To install TypeDoc just run this command:

npm install --global typedoc

3. NET Core SDK (version 2.1 or higher)

AistDoc is distributed as a .NET Core global tool. So, obviously you need to install it before installing the utility itself.

4. Aistdoc

Aistdoc is a .NET Core global tool, so its installation is quite simple:

dotnet tool install -g Aistant.DocImport

To update it to the latest version, if it was installed previously, use:

dotnet tool update -g Aistant.DocImport

Step 2. Documenting your code with TSDoc

TypeDoc utility will scan your TypeScript code and gather information about all code structures (modules, namespaces, classes, interfaces, enums, etc) to a special JSON file. If you what to add some descriptions to all those structures you can comment your code with a special comments in TSDoc format (a superset of JSDoc).

Step 3. Running TypeDoc to get JSON files

When all installations are done and your code is properly commented - you might proceed to the next step and generate the documentation for your project.
Use the following command to get a JSON file with API reference for one package of your code:

typedoc --out docs /src

You can also apply TypeDoc during your building process with WebPack or other build tools. Take a look at TypeDoc installation guide for more information.

Step 4. Registration on Aistant.com

So, the information about your TypeScript code is ready for publishing. Now you need to register a new account on Aistant (if you don't have it yet). The registration is free and will take about 1 minute. NB: Please, choose "Empty" option when it asks about your new Knowledge Base's default content.

After the registration please open Users page in Aistant Console and set the password for the special service account (YourTeamID-clientapp@aistant.com) which was created automatically for your team. Save the password somewhere. It will be used to setup the credentials to your Aistant account in the configuration file for AistDoc (see below).

Step 5. Configure aistdoc

Finally we need to configure our aistdoc tool to tell it which files to proceed and where to publish the result. Aistdoc reads all settings from a special JSON configuration file. To generate a template for that file use the following command:

aistdoc create -f:<config file name> -m:ts 

Here -f (or --file) parameter allows to specify the name of the config file and -m (or --mode) defines the mode (either ts for TypeScript or cs for C#).

For example, the following command

aistdoc create -f:mylib.json -m:ts 

will create mylib.json config file in the current folder.

The config file has 2 main sections: aistant and source.
The first one contains the credentials to your Aistant account, the ID of the knowledge base and the URL to the section where your documentation will be published. The second one includes the path to your assemblies and XML files with the documenation.

All properties are well commented. Here is an example of the configuration file (we suppose there that the team's ID is myteam and the knowledge base's ID is mykb):

{
  "aistant": {
    "username": "myteam-clientapp@aistant.com",
    "password": "qwerty!12345",
    "team": "myteam",
    "addVersion": false,
    "publish": true,
    "kb": "mykb",
    "section": {
        "uri": "mylib-api-reference",
        "title": "My Library API reference"
    }
  },
  "source": {
    "mode": "typescript", //the type of the source (either "csharp" or "typescript")

    //TypeDoc JSON files. Required.
    "files": [
      "docs/my-package1.json",
      "docs/my-package2.json"
	]
  }
}

The latest (files) section of the config file contains the list of paths to JSON files generated on the previous step 3.

Step 6. Generating and uploading the documentation

When the configuration file is ready you can start the publishing of your API reference to Aistant with the followng command:

aistdoc publish --config:<Config file path>

For example:

aistdoc publish --config:mylib.json

That's all. Enjoy!

Contact information

Feel free to contact us if you have any questions or suggestions about AistDoc utility or Aistant service. The source code for Aistdoc is published on GitHub - so you can fork the repository and to make your own adjustments or to submit an issue if you want some new feature or found a bug.