Table of Contents

• Introduction
• Dependencies
• Customization of the generation template
• Generation and releasing

Introduction

The original repository for the JM2MP document format and this JM2MP.JS library, https://github.com/JSON-MDE/JM2MP.JS, contains not only the source code but also a complete set of documentation.

This tutorial will guide you through the process of generating that documentation, combining comments from the original source code with additional material like all existing tutorials.

Dependencies

The JM2MP.JS library uses the documentation template tidy-jsdoc, which in turn is based on and uses JSDoc as documentation generation engine.

Both dependencies parse, extract and manage all JSDoc comments found in the library's source code.

In addition, several tutorials have been written using Markdown (such as this one), to introduce, guide you through, and document all aspects of the JM2MP document format and this JM2MP.JS JavaScript library.

Customization of the generation template

The tidy-jsdoc template used by JM2MP.JS requires some customizations in order to produce the desired results.

The directory ./doc/jsdoc/ contains all these customizations:

• The subdirectory ./doc/jsdoc/static/ is configured to be copied to the generated documentation, and as its name implied, contains static files (CSS stylesheets, images and TXT website files).

• The subdirectory ./doc/jsdoc/tmpl/tidy-jsdoc/ contains modified files to be manually overwritten over the distributed tidy-jsdoc source code, before the generation process runs.

  It's worth noting the JavaScript code injections in tutorial.tmpl used to properly configure the table of contents and mark external links in each Markdown-based tutorial.

• The subdirectory ./doc/jsdoc/tutorials/ contains all tutorials for JM2MP.JS, presented using the additional configuration file tutorials.json.

The ./src/README.md and ./src/LICENSE.txt files are also included into the final documentation generated.

The file ./src/JSDoc.config.json contains the configuration for both JSDoc (about configuring the engine) and tidy-jsdoc (customize the template), in order to properly generate the desired final documentation.

Generation and releasing

The JM2MP.JS project file, ./src/package.json, defines several scripts to completely generate the project documentation:

  "scripts": {
    "all": "npm run test:coverage && npm run eslint && npm run jsdoc",
    "jsdoc": "npm run jsdoc@windows",
    "jsdoc@windows": "DEL /Q /F /S ..\\doc\\jsdoc-out\\ && .\\node_modules\\.bin\\jsdoc.cmd --configure .\\JSDoc.config.json",
    "jsdoc@linux": "./node_modules/.bin/jsdoc --configure ./JSDoc.config.json",
    // ...other scripts also declared.
  },

As you can read, by default documentation generation will execute the Windows version but it is easy to change such configuration to execute by default the Linux/UNIX variation. Note that these changes can be applied to both JSDoc (document generation) and AJV-CLI (CLI for JSON-Schema validator).

Executing npm run jsdoc from ${JM2MP.JS_ROOT}/src/ in your shell will create a new directory ${JM2MP.JS_ROOT}/doc/jsdoc-out/ containing the final documentation, which can be archived using any utility (like TAR or GZIP, to name a few) and released as desired.

The original source code repository https://github.com/JSON-MDE/JM2MP.JS contains a copy of all releases made, including both source code and documentation.