grunt-sildoc
v0.1.1grunt-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:
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - 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.