grunt-readmejs

generate README.md from documented code

Getting Started

This plugin requires Grunt.

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-readmejs --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('readmejs');

Example output

README-CUSTOM.md generated by this plugin.

The "readmejs" task

Overview

In your project's Gruntfile, add a section named readmejs to the data object passed into grunt.initConfig().

grunt.initConfig({
  readmejs: {
    options: {
      separator: '-----------------------',
    },
    index: {
      options: {
        showFilePath: false,
        header: 'HEADER.md',
        footer: 'LICENSE.md'
      },
      files: {
        'README.md': ['*.js']
      }
    },
    lib: {
      options: {
        showFilePath: true
      },
      files: {
        'README.md': ['lib/**/*.js']
      }
    }
  },
})

Options

options.showFilePath

Type: Boolean Default value: false

Set to true if you wish to output the path of the file.

options.compressed

Type: Boolean Default value: false

Set to true if you want your output compressed (titles and such are taken out).

options.quoteSummary

Type: Boolean Default value: false

Set to true if you want to quote > your summary block.

options.header

Type: String Default value: ''

Path to a header file to be concatenated at top of output.

options.footer

Type: String Default value: ''

Path to a footer file to be concatenated at bottom of output.

Usage Examples

Default Options

In this example, no header or footer will be used, and the result will be the parsing from all the matched files.

grunt.initConfig({
  readmejs: {
    options: {},
    files: {
      'lib/README.md': ['lib/*.js']
    },
  },
})

Custom Options

grunt.initConfig({
  readmejs: {
    options: {
      showFilePath: true,
      compressed: true,
      quoteSummary: true,
      header: 'HEADER.md',
      footer: 'LICENSE.md'
    },
    files: {
      'README.md': ['lib/**/*.js']
    },
  },
})

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History

(Initial release)

License

Copyright (c) 2014 Acatl Pacheco. Licensed under the MIT license.