Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Simple Language-agnostic Documentation Compiler

branch: master
README.md

grunt-sildoc Dependency Status

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 concatenating 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 used globbing (such as src/*.jst) as source, the concatenating order would been: content, footer, and header. Therefore, the declaration order of 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 target 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: a leading underscore into the filename (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 via the partials object. (Inside this object, the name of the partial is the same of its filename, stripped out of the leading underscore and all the suffixes).

If an index is required, a <%= index %> tag must be defined into the template, at the position where we want it to be inserted. 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.contents %>
<%= partials.footer %>

The file _header.md.jst:

# HEADER

<%= index %>

## Introduction

<%= meta.loremIspum %>

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']
    }
  }
})

That's what we should obtain as result:

# HEADER

* [Introduction](#introduction)
* [CONTENTS](#contents)

## Introduction

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

## CONTENTS

Lorem ipsum dolor sit amet, consectetur adipisicing elit.
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
Lorem ipsum dolor sit amet, consectetur adipisicing elit.

---
document - Copyright (c) 2013

NOTE: due to the recursive nature of the internal template processor, to avoid the unwanted processing of template tags, you MUST insert an exclamation point (!) between the opening angular parenthesis and percent sign (<!%). These forcedly unmanaged tags will be restored to their correct values once the template will be completely processed, just before to write the results on disk.

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:

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.

Something went wrong with that request. Please try again.