grunt-sildoc

Simple Language-agnostic Documentation Compiler

Getting Started

This plugin requires Grunt ~0.4.1

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-sildoc --save-dev

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

grunt.loadNpmTasks('grunt-sildoc');

The "sildoc" task

Overview

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

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

sildoc is the acronym for Simple Language-agnostic Documentation Compiler (Si.L.Do.C.). Its goal is to make easier the procedure of generating project documentation, by allowing the developer to use Grunt's internal templating processor to process documents with external custom data. This README file itself was generated with this plugin.

Options

options.* | Type | Default | Description ---|:-:|:-:|--- meta|Object|{}|used in global task options only. It allows to specify custom data to be used inside the template processor index|String|'none'|specifies the format for the required index to be generated. Supported values are: none, gfm. mainHeading|Boolean|false|specifies if the main heading (the one that begins with #) have to be included into the generated index template|String|''|file path to the template to use. If no file is provided, the document will be generated by concatenation of all the specific target's sources data|Object|{}|used in local target options only. It allows to specify local custum data to be used inside the template processor. It is mixed with options.meta data.

Usage Examples

Default Options

If no options are specified, the generated document will be the result of all its source files concatenated in loading order. No data will be available inside the template processor.

In this example, the file dest/document.md is built starting from src/header.md.jst, src/content.md.jst, and src/footer.md.jst.

grunt.initConfig({
  sildoc: {
    options: {},
    files: {
      'dest/document.md': ['src/header.md.jst', 'src/content.md.jst', 'src/footer.md.jst']
    }
  }
})

Please, note that if we had specified src/*.jst as source, the concatentaion order should been: content, footer, and header. So, the order of declaring the sources is important, when we don't use a template file.

Custom Options

It's possibile to specify options globally (per task) and/or locally (per target). All the options (except meta and data) can be specified either globally or locally. Instead, meta option can be used only to specify global data (consumed by all the targets), and data option can be used to specify local data (consumed by the specific taget only). Inside the template processor, global and local data are mixed together and available via the meta object.

When a template file is specified, all the sources are considered partials and loaded only if their file name follows a simple rule: an underscore heading the name (for example, _header.md.jst, _footer.txt, etc.). If the rule isn't satisfied, the file is discarded and a warning is printed out on the console. Inside the template it will be possibile to reference at those partials file via the partials object. (Inside this object, the name of the partial is the same of its filename, without the heading underscore and all the suffixes).

If an index is required, a <%= index %> tag must be defined along the template, into the place we want the index will appears. Currently only GitHub Flavoured Markdown indeces are supported. (Github automatically generates the link reference for each heading in document, so the index just targets the link to that reference.)

In this example, the file dest/document.md is built starting from src/_header.md.jst, src/_content.md.jst, and src/_footer.md.jst. The template src/document.md.jst is used.

The file document.md.jst:

<%= partials.header %>
<%= partials.content %>
<%= partials.footer %>

The file _header.md.jst:

# HEADER

<%= index %>

## Introduction

<%= meta.loremIpsum %>

The file _content.md.jst:

## CONTENTS

<% for (var i = 0; i < 10; i++) { %>
   <%= meta.loremIpsum %>
 } %>

The file _footer.md.jst:

---
<%= meta.name %> - Copyright (c) <%= grunt.template.today('yyyy') %>

The task:

grunt.initConfig({
  sildoc: {
    options: {
      meta: {
        loremIpsum: 'Lorem ipsum dolor sit amet, consectetur adipisicing elit.',
        name: 'document'
      },
      template: 'src/document.md.jst',
      index: 'gfm'
    },
    files: {
      'dest/document.md': ['src/_*.jst']
    }
  }
})

Contributing

Any contribution to improve the project and/or expand it is welcome.

If you're interested in contributing to this project, take care to maintain the existing coding style.

The project follows these standard, so please you do it too:

• SemVer for version numbers
• Vandamme for changelog formatting
• EditorConfig for cross-editor configuration

To contribute:

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History

See the CHANGELOG file distributed with the project.

License

Copyright (c) 2012-2013 Marco Trulla. Released under the MIT license.

See the LICENSE file distributed with the project.