grunt-moduledoc
Creates a frontend module documentation
Getting Started
This plugin requires Grunt ~0.4.5
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-moduledoc --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt;
Documenting modules
Create a YAML file for each module.
A module must have:
- A
title
: Legal characters are capital letters and underscores. - A
dom
: The HTML node type
File header.yml
:
title: HEADERdom: header
defines:
<header> ... </header>
Class
Typically a module will have a unique CSS class. We use the ui-
prefix to denote ui modules, but that is optional.
title: HEADERdom: headerclass: ui-header
defines:
<header class="ui-header"> ... </header>
Type
A module can also optionally belong to a type. We use the type-
prefix to denote a type. This allows us have a generic class across a number of modules.
title: HEADERdom: headertype: type-headerclass: ui-header
defines:
<header class="type-header ui-header"> ... </header>
Description
You can add a one line description to the module.
title: HEADERdescription: The main site header.dom: headertype: type-headerclass: ui-header
Options
You can add one or more option classes to a module. An option class should in some way alter the display of the module. We use the opt-
prefix to denote an option.
title: HEADERdescription: The main site header.dom: headertype: type-headerclass: ui-headeroptions: - class: opt-dark description: Displays the header with a dark background and white text. - class: opt-minimal description: Displays a minimal header.
Contains
Most importantly, modules can contain other modules. Add them to the contains
list. They will be linked in the documentation.
title: HEADERdescription: The main site header.dom: headertype: type-headerclass: ui-headeroptions: - class: opt-dark description: Displays the header with a dark background and white text. - class: opt-minimal description: Displays a minimal header.contains: - LOGO - NAV_MAIN
You will of course have to create module YAML files for each contained module, which can also contain modules.
Optional and multiple contains
You can add a suffix to a contained module to denote how often it can be contained.
contains: - REQUIRED - OPTIONAL ? - MULTIPLE + - OPTIONAL_MULTIPLE *
Modules without a suffix are considered required.
Modules with ?
are considered optional.
Modules with +
are considered multiple (i.e. one or more occurances).
Modules with *
are considered both optional and multiple (i.e. zero, one or more occurances).
Inner DOM wrappers
A module might often contain an inner wrapper that in turn contains the contained modules.
You can document this by adding it to the dom
setting.
dom: div>div.wrapperclass: ui-block
defines:
<div class="ui-block"> <div class="wrapper"> <!-- modules go here --> </div></div>
You can also define the wrapper as its own module, e.g. WRAPPER
, and then use that:
name: WRAPPERdom: divclass: ui-wrapper
name: BLOCKdom: div>WRAPPERclass: ui-block
defines:
<div class="ui-block"> <div class="ui-wrapper"> <!-- modules go here --> </div></div>
The "moduledoc" task
Overview
In your project's Gruntfile, add a section named moduledoc
to the data object passed into grunt.initConfig()
.
grunt;
Options
options.templatepath
Type: String
Default value: templates/module.mustache
Path to the module template.
options.assetspath
Type: String
Default value: templates/assets
Path to the assets directory.
Usage Examples
Default Options
grunt;
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.
Tests
grunt test