Extend JSDoc API documentation through tutorials

JSDoc aids in the creation of API documentation for JavaScript projects by maintaining a close relationship between source code and documentation content. After comparing tools for JavaScript API documentation, we decided on JSDoc for documenting the FusionCharts library. Though JSDoc may appear to be a bit large for smaller projects, it has a lot of power under the hood. JSDoc can be used to write additional articles that can be shipped with the API documentation in addition to annotating source code. In JSDoc parlance, these articles are referred to as “tutorials.” Tutorials are one of JSDoc’s less-used features, but they are extremely useful for a documentation team attempting to ship a unified documentation pack for its product. In this blog post, we’ll discuss how tutorials can be created, organized, and rendered with API documentation using JSDoc. If you’re looking for a Data Visualization Tool, we suggest using fusioncharts for creating tutorials.

Creating tutorials

Tutorials can be written as Markdown or as pure HTML. So, each tutorial in JSDoc is either a Markdown or a HTML file with just the content of the article. JSDoc takes care of putting the content in the right place, applying styles to the text and generating a separate page for the tutorial within the documentation output. e.g., a tutorial file can be named getting-started.md.

Linking to a tutorial

The name of the file, without the extension, becomes the internal machine name of the tutorial. This name can be used in the annotated source or in other tutorials to link to the tutorial using @tutorial directive. So, the internal name for the tutorial in our example would be getting-started and the code to link to it from a documentation block would be:

@tutorial getting-started

When linking from another tutorial, the directive has to be wrapped in curly braces, so the code will become:

{@tutorial getting-started}

On compilation, JSDoc will replace that portion with a link to the tutorial file.

Provide meta information for tutorials

A tutorial can be accompanied by an optional JSON file containing meta information about the tutorial. This file has to be named the same as the tutorial it refers to. The JSON meta file name for the tutorial example mentioned above will be getting-started.json. The content of the JSON meta file is an object with two important properties. Both the properties are optional:

• title: This value becomes the tutorial’s title. It is shown on the tutorial’s page as the page title and is used as the anchor tag text in links to the tutorial. This is different from the internal machine name. The internal machine name of a tutorial is always derived from the file name. So, a tutorial’s title can be changed anytime without changing its filename. If the title is changed, all references to that tutorial will automatically update to the new title provided.
• children: This is an array of tutorial names that are rendered as children of the current tutorial. More on this in the following section.

An example of content for the JSON file can be:

{
    "title": "Getting Started",
    "children": [
        "building-your-first-chart",
        "configuring-your-chart"
    ]
}

Nesting tutorials as children

Tutorials can be specified as children of other tutorials through the children property in the parent tutorial’s JSON metadata. This helps in organizing entire documentation into a tree with neat sections. The nesting, however, is at the meta level. The child tutorials still remain in the same location, their file names upon compilation remain the same. They simply show up as sub-articles under their parent tutorial in the generated documentation and do not appear on the main “Tutorials” menu anymore. JSDoc handles any cyclic dependency which may result from specifying the parent tutorial in the children property of the child tutorial. In this case, JSDoc takes only the first instance of the relation. If it already knows that a given tutorial is a child of a parent, it will ignore any further relation it finds to the parent from the child.

Organizing tutorials

As of JSDoc 3.3.0-alpha5, all tutorials have to be put in one folder. The tutorial parser only checks in the first level of that folder and does not recurse in subfolders. This may prove to be problematic for documentation projects having more than 100 articles as tutorials. Things tend to go out of control very soon if proper file names are not used to namespace sections in the documentation. At FusionCharts, we handled this issue by keeping our tutorial files in different directories and writing a script which copies them to one temporary directory each time JSDoc is run.

Rendering tutorials

Finally, let us look at how to build tutorials along with API documentation. There are two ways to do this: directly passing the path to the tutorials folder on the commandline or adding the path to JSDoc’s configuration.

Passing path to tutorials folder on commandline

JSDoc provides the -u switch for providing path to the tutorial folder. This path is relative to the directory from which JSDoc is executed. Assuming the tutorials are kept in ./docs/tutorials, the command for running JSDoc has to be modified to:

$ jsdoc [options] -u "./docs/tutorials"

Even if the tutorial path is specified in the configuration, specifying it on the commandline takes precedence over the configuration.

Specifying tutorial path in the configuration

If the project uses a configuration file for JSDoc, the configuration file needs a new property called tutorials under the opts property in the configuration. The value of the tutorials property will be a string containing relative path to the tutorials directory. Taking the same example above, the configuration file would look like:

{
    …
    "opts": {
        …
        "tutorials": "./docs/tutorials"
    }
}

Why not write documentation separately?

The main reason is: the entire documentation is served as one single package. If a product has an API whose end users are developers, it would aid the end-users greatly if they could have more clarity on how a particular method works and when they should use it. Also, if an API method, event, member, or namespace needs elaboration, it becomes unmanageable to write lengthy details in the source code annotation. It gets troublesome for an end-user to read such documentation. So, it makes sense to write lengthy details as a separate article and link that article from the API item. On top of that, the documentation source can be version controlled and be part of the project repository. How cool is that? At FusionCharts, we have adopted JSDoc tutorials extensively in our documentation and we are happy with the flexibility we have.