Photo Credit: Paul Earle

Create Beautiful Documentation

A Guide to Generating Documentation with TypeDoc and Jekyll

Our goal at IronCore Labs is to make the digital world a safer place for data by making it easy for developers to add world-class security to their applications. The process must be easy to spark rapid adoption and widespread integration. Consequently, excellent documentation, including an engaging UI and easy-to-follow guides, is a priority for us.

IronCore is an engineering-centric company with an experienced team. We want to automate the generation of our documentation to keep it up-to-date and to minimize manual labor wherever possible. Further, we believe that code-specific documentation should live in the relevant code repository and be maintained in the same way we maintain code. For example, documentation updates should be reviewed alongside code updates in pull requests.

Alas, documentation generated from the code only takes us so far. Generated documentation tends to be lower-level. This is useful, but not sufficient; users also need a broad map to guide them to the functions they need to look at in the first place. Excellent user guides require an experienced developer to write higher-level docs to point the way, along with detailed docs to help developers once they know where to drill down.

Start with Inspiration

At Apple, we used to spend weeks gathering inspiration. — Daniel Scrivner

Weeks may seem like a luxury to any startup or engineering team, but time devoted to design thinking pays dividends. The first thing we did at IronCore was to identify examples of delightful developer experiences and use them for inspiration when designing the UI and UX for our documentation. Some of the sites we looked at included Stripe, Square, and React Router.

While there were significant aspects of Stripe and Square’s documentation that inspired us, both services separate their API documentation from their developer documentation with a stark UI shift. The disjointed experience left us feeling disconnected and confused.

Generating Documentation from TypeScript

Install

After careful consideration of multiple tools that generate documentation, TypeDoc stood above the rest as the best fit for our needs. To install TypeDoc, run the following:

// yarn //
yarn add typedoc --dev
// npm // 
npm install typedoc --save-dev

Configure TypeDoc with tdconfig.json

TypeDoc can export documentation in one of two ways: it can either generate a full website with HTML, styles, and links, or it can export JSON. We wanted our code docs to be integrated with other docs and the rest of our site, so built-in HTML templates don’t work for us. Instead, we generated JSON that we can later import and format in Jekyll.

The first step, in either case, is to create a config file, which lives in the root directory of the project repo. This file, tdconfig.json, specifies the options used to compile the code and generate documentation. Its format is similar to that of tsconfig.json, the file that is needed in any TypeScript project to specify how to compile and serve the project.

There are three main sections in the tdconfig.json file. First, the compilerOptions section includes the same compiler options as TypeScript. Next are the include and exclude sections. These sections specify which files will be documented by TypeDoc and which will not. We included our global definition file and other specific files and excluded our node_module and test files.

// tdconfig.json //
{
"compilerOptions": {
    "moduleResolution": "node",
    "lib": [
        "es6",
        "dom"
    ]
},
"include": [
        "globals.d.ts",
        <Include file paths to documents that should be documented.>
        "src/file1.ts",
    ],
"exclude": [
        "node_modules",
        "src/**/*.test.ts"
    ]
}

Generate

The minimal command for generating docs in JSON format is:

typedoc --json apidocs.json --mode modules --tsconfig tdconfig.json

Command-line Options

TypeDoc exposes additional options that can be added to the minimal generation command mentioned above to keep the generated JSON file clean and specific. Here are the options IronCore uses:

--excludeExternals
** Excludes files that are not explicitly exported.
--excludeNotExported
** Excludes items within files that are not explicitly exported.
--includeDeclarations
** Include type declaration files (**.d.ts) in exported documentation.

Using Jekyll Templates

Generating documentation via an automated method creates reference materials that are tightly coupled and always in sync with a codebase, but they only get us so far.

To design a delightful developer experience, code documentation should be integrated with guides, tutorials, architecture specifications, and other long-form content. Jekyll provides a solution that merges documentation written by experienced developers and documentation that is generated via TypeDoc.

Jekyll is a static site generator that integrates with Github Pages and conveniently works with JSON files which can then be accessed through the variable site.data and added to static templates written in markdown or HTML. In our case, we already use Jekyll for our website, so we can easily share headers, footers, and styles.

Here is a simple example to render JSON data within a Jekyll template:

{% assign documentedfiles = site.data.apidocs %}
## Files documented
{% for file in documentedfiles %}
    The next file name we want to document is: {{ file.name }}.
{% endfor %}

The objective is to render the exported file names listed in the imported JSON. To do so, we assign a variable name to represent all of the JSON data. Jekyll is opinionated about its file structure, so data files must live inside the _data directory. Henceforth, we can access this data by calling site.data followed by the data file name. In the example, the path apidocs references the imported JSON file containing our raw documentation data. Next, we iterate through each of the file names listed inside of the produced JSON output, printing it within a section header in the Jekyll template.

Wrapping Up

Documentation should always be clear, even if the process of implementation is complicated. It should provide defined methods and guides that lay out a roadmap to users getting started with any new system or product.

Generating dense documentation of functions is pretty easy, but making a coherent and friendly developer experience requires extra care. IronCore uses tools like TypeDoc and Jekyll to keep the system simple and manageable, while leaving room for customization.

IronCore’s Documentation site is currently in beta mode and will be coming soon. To be notified upon release, sign up for our email list and we will keep you in the know.