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.
Nesting tutorials as
Tutorials can be specified as children of other tutorials through the
Table of Contents
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 namedgetting-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-startedWhen 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 begetting-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.
{
"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 calledtutorials 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"
}
}
