grunt-jsdoc2md

Generate markdown api documentation from jsdoc.

content

• Usage (see further down this page)

  • Getting started guide
  • Usage and examples
  • Maybe look at the projects config?

• Developers

  • Testing grunt-jsdoc2md
  • Code coverage of tests for grunt-jsdoc2md
  • Build grunt-jsdoc2md from scratch
  • NPM integration of grunt-jsdoc2md
  • Frameworks used for testing, building, etc.
  • API of package grunt-jsdoc2md (self generated with grunt-jsdoc2md)

Changelog

getting started

This guide assumes, that you are familiar with the use of npm and grunt.
The plugin can be installed by the following command:

npm install grunt-jsdoc2mds --save-dev

Once installed, the plugin may be loaded from within your gruntfile.

Setup the task configuration as described below (see usage) and run the task:

grunt jsdoc2md

Of cause, the task can be integrated into any complex build process.

usage

Basically this module does the same as grunt-jsdoc-to-markdown ... with additions:

1. Internal use of dmd plugin dmd-readable to make things more ... readable :-)
2. In case multiple markdown files are created into a directory tree, an index file is created, to link the outputfiles together.

// from jsdoc2md.js for use with load-grunt-config

module.exports = function ( grunt, options ) {
  return {
    options: {
      // options to use with every target
      // basically all options, which are accepted by
      // 'jsdoc-to-markdown', can be added here.
    },
    target1: {
      // multiple source files to directory with multiple markdown files
      src: "src/lib/**/*.js",         // glob which will resolve to multiple sourcefiles
      dest: "docs/api/",              // destination 'directory' (defined by ending slash)
                                      // ... this is where the markdown files will be created.
      options: {                      // options to use with 'target0'
        index:  {                     // create an index file
          dest:     "docs/api.md"     // name it 'api.md' and place it in the docs directory.
          // template: "partials/api.hbs"   // use the named template to create the index file.
        }
      }
    },
    target2: {
      files: [
        // single source file to single markdown file
        { src: 'src/lib/tasks/jsdoc2md.js',   dest: 'src/test/tmp/api/tofile/1/jsdoc2md.md'       },
        // missing source file ... producing no output but a warning message
        { src: 'src/does.not.exist.js',       dest: 'src/test/tmp/api/tofile/2/missing.src.md'    },
        // multiple source files to single (aggregated) markdown file
        { src: 'src/lib/**/*.js',             dest: 'src/test/tmp/api/tofile/3/aggregated.api.md' },
        // multiple source files to directory creating multiple markdown files
        { src: 'src/lib/**/*.js',             dest: 'src/test/tmp/api/tofile/4/' },
        // multiple source files to directory creating multiple markdown files
        { src: 'src/test/templates/**/*.js',  dest: 'src/test/tmp/api/tofile/5/' }
      ]
    }
  };
};