Introducing Bouquet – an open source collection of JSDoc plugins

Last week, FusionCharts released another open source tool, a collection of JSDoc plugins, called “Bouquet”. At present Bouquet is made up of one plugin, which is somewhat contrary to its name. We plan on adding more plugins to this collection in near future and make it true to its name! This set of plugins will be very handy for developers writing their JavaScript source code documentation using JSDoc.

Why this collection of plugins?

In the post on comparison of JavaScript documentation generators, we had mentioned that JSDoc can be highly extended with plugins. After FusionCharts decided to use JSDoc internally for the next release, we faced the need to customize and extend directives, file copying and other such aspects of JSDoc to suit our needs. One of our first tasks was to support copying of static files, like images, which we use in writing JSDoc tutorials. We figured it’s best to implement this feature as a plugin for JSDoc, which can then be reused for other projects. Forking JSDoc and adding this functionality to its core would not have been a future-proof solution. It would require us to update our fork of JSDoc whenever any changes were released in the original project. Building this as a plugin will let us keep our existing copy of JSDoc and add the plugin on top of it for added features. After writing the first plugin, we figured out that we need a good number of others. We also wanted to release each of these plugins out to the world and let them share our innovation. But releasing each plugin separately would create different scattered repositories. Instead, publishing all plugins in a single repository will be more reusable, discoverable and maintainable.

staticFiles – our first plugin for JSDoc

staticFiles is the first plugin in this collection. It helps to include static assets in the compiled documentation, which can be any file or directory that the documentation needs. For example, in a tutorial written for the upcoming version of FusionCharts XT, we needed to document how to export a chart to an image or PDF. This needed us to show some screenshots clearly showing users where they need to click to get the exported image. With staticFiles, we can now put the images in a specific source folder, get the output in a specified destination folder and link the images with a relative URL from the tutorials. Similarly, there can be other use cases like including raw JSON data files in the documentation or shipping source PSD files with the documentation, that is, packaging files which are not part of the core documentation. So far the only other way to achieve this in JSDoc was to use a similar inbuilt feature which runs from the template layer. We opted to create a generic solution.

How to use staticFiles?

0. Download the Bouquet repository from Github. 1. To install staticFiles, copy `src/staticFiles/` to `plugins` folder located in the JSDoc installation folder. 2. Then, include the plugin in jsdoc.conf (assuming that the configuration file used to generate JSDoc’s documentation is called jsdoc.conf) by adding its path to the `plugins` array. For this do:

{
    “plugins”: [“plugins/staticFiles/staticFiles”]
}

The plugins folder is the recommended location for a plugin. It can be optionally put in any other location, in which case, jsdoc.conf needs to know the relative or absolute path to the plugin.

3. staticFiles uses a special set of configurations that will be familiar to JSDoc users. All these configurations go to `jsdoc.conf` We need to use the following set of configurations at the bare minimum:

{
    “staticFiles”: {
        “include”: [“images:tutorials/images”]
    }
}

This tells staticFiles to include all files in the `tutorials/images` folder and copy them to the `images` folder within the documentation output directory. `include` is an array of strings containing file paths in the format `destination:source`. Multiple include file paths can be provided by separating them with a comma within the square brackets. By default it will not copy recursively. For recursive copying, set `”recursive”: true` like this:

{
    “staticFiles”: {
        “include”: [“images:tutorials/images”],
        “recursive”: true
    }
}

4. Run JSDoc and pass this conf file to it:

$ jsdoc -c jsdoc.conf

For more detailed instructions and information on other configuration options, take a look at the staticFiles documentation.

What’s next?

This is just the start, we plan to create even more plugins for JSDoc in the near future. These include plugins which will perform a global search across the generated documentation entirely on the client side, produce reports on documentation coverage, embed fiddles from JSFiddle and live charts generated documentation. If you have any suggestions, please let us know in the comments below, or even better, file a bug or a feature request in the Bouquet issue tracker.