esdoc-plugin-jspm

A plugin for ESDoc that enables end to end Javascript ES6 documentation linking JSPM / SystemJS managed packages in addition to a local source root. This allows creating comprehensive documentation that includes JS managed by JSPM / SystemJS.

Installation steps:

• Install esdoc or gulp-esdoc in devDependencies in package.json.
• Install esdoc-plugin-jspm in devDependencies in package.json.
• Create an .esdocrc or esdoc.json configuration file adding the plugin.
• Add an .esdocrc or esdoc.json configuration file in all JSPM managed packages to link.
• Run ESdoc then profit!

For more information view the ESDoc tutorial and ESDoc Config documentation.

It should be noted that all TyphonJS repos now are standardizing on .esdocrc for the ESDoc configuration file. Both .esdocrc and esdoc.json are supported by this plugin.

As an alternate and the preferred all inclusive installation process please see typhonjs-npm-build-test for a NPM package which contains several dependencies for building / testing ES6 NPM modules including ESDoc generation with the following plugins including esdoc-plugin-jspm, esdoc-plugin-extends-replace.

Additionally typhonjs-core-gulptasks provides a NPM package which contains several pre-defined Gulp tasks for working with JSPM / SystemJS, ESLint and ESDoc generation.

For the latest significant changes please see the CHANGELOG.

Please see the backbone-parse-es6 repo for an example using esdoc-plugin-jspm via typhonjs-core-gulptasks.

If installing and working directly with esdoc-plugin-jspm the following is an example integration for package.json:

{
  ...

  "devDependencies": {
    "esdoc-plugin-jspm": "^0.6.0",
    "jspm": "^0.16.0",
    "gulp": "^3.9.0",
    "gulp-esdoc": "^0.2.0",
  },
  
  "jspm": {
    "main": "src/ModuleRuntime.js",
    "dependencies": {
      "backbone-es6": "github:typhonjs/backbone-es6@master"
    },
     "devDependencies": {
      ....
    }
  }
}

And the .esdocrc or esdoc.json configuration file:

{
   "title": "<title>",
   "source": "src",
   "destination": "docs",
   "plugins": [ { "name": "esdoc-plugin-jspm" } ],
   "jspmRootPath": "<path to JSPM root>" // (Optional) - specifies the root path where JSPM `package.json` is located.
}

For the example above the local source root is src and the ESDoc documentation is output to docs. All JSPM packages found in package.json in the jspm.dependencies entries will be parsed including any child dependencies defined in config.js are linked if they contain a valid .esdocrc or esdoc.json file in the respective root paths. In the case of the repo above the linked JSPM package is backbone-es6.

A .gitignore will be added to the docs directory that ignores all unnecessary files for checking into a repository.

An optional top level entry, jspmRootPath to ESDoc configuration file may define the JSPM root path; often this is added programmatically IE typhonjs-core-gulptasks for instance. If jspmRootPath is not defined JSPMParser.getRootPath() locates the root execution path. The root path is where the JSPM package.json is located.

If an option.packages entry is supplied only those top level packages and their dependencies will be parsed. Likewise if an option.devPackages entry is supplied only those top level dev package and their dependencies will be parsed. This is only necessary when it's desired to specifically limit linking. By default with no option.packages or option.devPackages entries all valid dependencies with a valid .esdocrc or esdoc.json file are linked. An optional entry option.silent if true suppresses logging output.

{
   "title": "<title>",
   "source": "src",
   "destination": "docs",
   "plugins": 
   [ 
      { 
         "name": "esdoc-plugin-jspm",
         "option":
         {
            "silent": false,  // (Optional) if true then there is no logging output from the plugin.         
            "packages": ["backbone"]  // (Optional) if provided this list limits linking to dependencies from `package.json`.
            "devPackages": ["babel"]  // (Optional) if provided this list limits linking to dev dependencies from `package.json`.
         }
      }
   ]
}

esdoc-plugin-jspm version 0.6.6 and greater exports to global.$$esdoc_plugin_jspm an object hash of all related parsed data for JSPM managed source code available via typhonjs-config-jspm-parse. The following is a synopsis of the exported data:

global.$$esdoc_plugin_jspm =
{
   childPackageMap,        // All child packages parsed from System / config.js
   jspmDevPackageMap,      // Top level JSPM packages taken from options and / or package.json jspm.devDependencies.
   jspmPackageMap,         // Top level JSPM packages taken from options and / or package.json jspm.dependencies.
   normPackageData,        // Normalized package data for all JSPM managed packages.
   normPackageDataESDoc,   // Normalized package data for all ESDoc enabled JSPM managed packages.
   rootDirName,            // Root directory name.
   rootPackageName,        // Root package name.
   rootPath,               // Root path
   topLevelPackages,       // All top level dependencies and dev dependencies.
   uniqueDeps,             // Unique package dependencies
   uniqueDevDeps,          // Unique package dev dependencies
   uniqueDepsAll           // All unique package dependencies
};

By exporting all of the parsed data to global.$$esdoc_plugin_jspm this allows any other ESDoc plugins which may utilize JSPM data to access it without also having to separately parse this data in each plugin.

---

esdoc-plugin-jspm version 0.6.6 and greater also adds to all ESDoc tags any associated JSPM package data for the given tag under tag.packageData with the package manager specified by tag.packageManager.

---

You may use any version of ESDoc, but as an example here is a simple Gulp task which invokes gulp-esdoc:

/**
 * Create docs from ./src using ESDoc. The docs are located in ./docs
 */
gulp.task('docs', function()
{
   var esdoc = require('gulp-esdoc');
   var path = require('path');

   var esdocConfig = require('.' +path.sep +'.esdocrc'); 

   // Launch ESDoc
   return gulp.src(esdocConfig.source).pipe(esdoc(esdocConfig));
});

If esdoc is installed in devDependencies an example NPM script section in package.json follow:

scripts: 
{
   "esdoc": "esdoc -c .esdocrc"
}

Use npm run esdoc on the command line to execute ESDoc w/ .esdocrc configuration file.

For a complete demo with instructions on how to use backbone-parse-es6 (Backbone + Parse 1.6+) with SystemJS / JSPM see the backbone-parse-es6-todos repo. Backbone, Parse, JSPM / SystemJS (setup, use, building), Gulp, ESLint and ESDoc is covered.

It should be noted that esdoc-plugin-jspm uses the includes ESDoc configuration parameter and will overwrite any includes top level entry stored in the ESDoc configuration file.

Currently the ESDoc Hosting Service isn't JSPM / SystemJS aware, so docs will have to be generated locally and hosted independently.

Check out the docs for backbone-parse-es6 and notice that when viewing ParseCollection that it properly contains links to the inheriting class from a JSPM package (backbone-es6) and also contains an Inherited Summary section for Collection & Event which is in the inheritance structure.

Without using esdoc-plugin-jspm the output only contains the local source. See the version of ParseCollection on the ESDoc hosting service for a comparison.

To suggest a feature or report a bug: https://github.com/typhonjs-node-esdoc/esdoc-plugin-jspm/issues

Many thanks to the ESDoc community for creating a valuable documentation tool.

esdoc-plugin-jspm (c) 2015-present Michael Leahy, TyphonRT Inc.

esdoc-plugin-jspm may be freely distributed under the MPLv2.0 license.