grunt-natural-docs

Builds NaturalDocs-based documentation.

Getting Started

This plugin requires Grunt ~0.4.0

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-natural-docs --save-dev

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

grunt.loadNpmTasks('grunt-natural-docs');

The "natural_docs" multitask

Overview

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

grunt.initConfig({
	natural_docs: {
		options: {
			// Task-specific options go here.
		},
		your_target: {
			// Target-specific file lists and/or options go here.
 		},
	},
})

Options

In this plugin, all settings may be specified as options. This makes it convenient to apply common settings for all tasks in the common options object. It is not necessary to have to include a target-specific options object. Instead, target-specific settings may be specified in the normal manner. These will override any options (task- or target-specific) given. In other words:

grunt.initConfig({
	natural_docs: {
		options: {
			src: 'As usual, this value is "default" for all targets'
		},
		your_target: {
			options: {
				src: 'This value will override the above task-level default'
			},
			src: 'And this will override them all.'
 		},
	},
})

And so, on to the options...

options.bin

Type: String

Default value: /usr/lib/bin/natural_docs

The NaturalDocs executable.

options.excludes

Type: Array of Strings

Default value: []

Identifies the source folders to be excluded (if starts with a /, assumed to reside under options.src).

options.flags

Type: Array of Strings

Default value: [ '-r', '-oft' ]

Additional flags (i.e. other than the mandatory flags, which are included automatically). To avoid any additional flags, simply provide an empty array.

options.format

Type: String

Default value: HTML

The output format.

options.inputs

Type: Array of Strings

Default value: []

Identifies the source folders (if starts with a /, assumed to reside under options.src).

options.output

Type: String

Default value: /docs

Identifies the output folder (if starts with a /, assumed to reside under options.src - and you'll want to exclude it).

options.project

Type: String

Default value: ``

Identifies the project folder (if starts with a /, assumed to reside under options.project).

options.projects

Type: String

Default value: /usr/lib/bin/natural_docs/projects

The folder under which the various NaturalDocs project files are stored. See options.project.

options.src

Type: String

Default value: ``

The source files root folder.

options.styles

Type: Array of Strings

Default value: [ 'Default' ]

Identifies the output folder (if starts with a /, assumed to reside under options.src - and you'll want to exclude it).

Usage Examples

grunt.initConfig({
	natural_docs: {
		options:    {
			bin:      'C:/path/to/NaturalDocs/NaturalDocs.bat',
			projects: 'C:/path/to/NaturalDocs/projects'
		},
		my_project:     {
			src:      'C:/path/to/my_project/src',
			project:  '/my_project',
			inputs:   [
				'/js', '/less', '/php'
			],
			excludes: [
				'/js/tests', '/php/tests', '/docs'
			],
			styles:   [ 'Default', 'MyProjectStyles' ]
		},
})

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

(Nothing yet)