node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

grunt-docma

grunt-docma

© 2017, Onur Yıldırım (@onury). MIT License.

DEPRECATED!

No need for this grunt task anymore. Since Docma has a CLI; you can simply add Docma to your scripts section in your package.json:

"scripts": {
    "docs": "docma -c ./docma.config.json",
    // your other scripts
},

...and run:

npm run docs

Grunt task for Docma, a powerful JSDoc and Markdown to HTML documentation generator, with a cool template. See Docma documentation for details and a live demo.

Getting Started

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 i grunt-docma --save-dev

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

grunt.loadNpmTasks('grunt-docma');

docma Task

Run this task with the grunt docma command.

Task targets and options may be specified according to the grunt Configuring tasks guide.

Task Options

Option Type Default Description
config Object|String (Default Config) Either a Docma configuration object, or a path to a Docma config file. See build configuration and default template options.
traceFatal Boolean|Number false On a fatal error (i.e. uncaughtException), Grunt exits the process without a stack trace. This option forces Grunt to output the stack trace. Possible integer values: 0 to 2. Set to 1 (or true) to only trace fatal errors. Set to 2 to also trace grunt warnings. This can also be achieved by the grunt --stack command.

Note that, if you set config option to a config-file path, you can also define src and dest within that configuration file. But if you additionally define these within the task configuration, it will be used instead.

CAUTION: Destination directory (dest) will be emptied before the build. Make sure you set dest to a correct path.

Example Task Configuration

grunt.initConfig({
    docma: {
        // Default options
        options: {
            // Task specific options
            traceFatal: true, // (0|false)|(1|true)|2
            // Docma specific config
            // See all @ https://github.com/onury/docma
            config: {
                jsdoc: {
                    encoding: 'utf8',
                    recurse: false,
                    pedantic: false,
                    access: null, // ['public', 'protected'],
                    package: null,
                    module: true,
                    undocumented: false,
                    undescribed: false,
                    hierarchy: true,
                    sort: 'alphabetic',
                    // 'relativePath': '../code',
                    filter: null,
                    plugins: []
                },
                debug: 0
            }
        },
        // your task target
        code: {
            // target specific options
            options: {
                // Docma config
                // See http://onury.github.io/docma/?api=docma#Docma~BuildConfiguration
                config: {
                    template: {
                        path: 'default',
                        // See all default-template options @
                        // https://github.com/onury/docma/tree/master/templates/default
                        options: {
                            sidebar: true,
                            collapsed: false,
                            badges: true,
                            search: true,
                            toolbar: true,
                            outline: "tree",
                            animations: true,
                            symbolMeta: false,
                            navbar: true
                        }
                    },
                    app: {
                        title: 'Documentation',
                        routing: 'query'
                    }
                }
            },
            // files to be processed
            src: [
                './test/code/**/*.js'
            ],
            dest: './test/doc'
        },
        // another task target that reads Docma config from file
        fromFile: {
            options: {
                config: './test/docma.config.json'
            },
            // overwrites src and dest defined in config file, if any.
            src: [
                './test/code/**/*.js'
            ],
            dest: './test/doc2'
        }
    }
});

Change Log

v1.0.0

  • Breaking Change: Docma (core) now requires Node.js v6 or newer.
  • Updated Docma core and dependencies. See Docma for changes.

v0.8.0

  • Updated Docma core and dependencies. See Docma for changes.

v0.7.0

  • Updated Docma core and dependencies.

v0.6.9

  • Updated Docma core and dependencies.

v0.6.6

  • Updated Docma core and dependencies.

v0.6.4

  • Updated dependencies (including Docma) to their latest versions.

v0.6.1

  • Fix package version.

v0.6.0

  • Updated Docma to initial release version 1.0.0. See Docma documentation for (breaking) changes.

v0.5.3

  • Task fails and aborts with stack and warnings instead of outputting only the stack.
  • Updated tests.

v0.5.2 (2016-05-22)

  • Added config from file support.
  • Updated Docma core.
  • Minor revisions.

v0.5.0 (2016-05-20)

  • Initial commit.

License

MIT.