jade-doc
v1.10.0
Published
Jade documentation generator.
Downloads
49
Maintainers
Readme
Jade-doc
Jade-doc is a Jade documentation generator. It takes Jade files as input, looks for comments flagged with @jadedoc
and puts its contents in an output JSON file.
This package does not provide a styled interface for the documentation itself. Use jade-doc-html or jade-doc-markdown for human readable docs. Optionally use jade-doc-faucet for prettier terminal reporting.
Usage
Use the keyword @jadedoc
to flag unbuffered block comments inside your jade files. Comments should be written in properly formatted YAML format.
//- @jadedoc
name: my jadedoc
description: this is a description for my jade doc
beep: boop
foo: faa
HTML Output
The immediate next Jade code block after the comment will be compiled to HTML output.
//- @jadedoc
name: some-node
div.this-is-output-for-jade-doc
div.this-isnt
Mixins
Optionally provide mixin arguments, attributes and example calls. If no examples are given, mixins will not be executed, so no output will be generated.
Arguments and attributes follow the jsdoc param syntax.
//- @jadedoc
name: my mixin
description: this is my mixin documentation
arguments:
- {string} arg1 - this is the description of arg1
- {number} arg2 - this is the description of arg2
attributes:
- {string} attr1 - this is the description of attr1
- {number} attr2 - this is the description of attr2
examples:
- +myMixin('foo', 1)
- +myMixin('faa', 2, attr1='foo', attr2='faa')
mixin myMixin(arg1, arg2)
div this is a mixin #{arg1} #{arg2} #{attr1} #{attr2}
Should you need multiline examples, use YAML's folded style, like:
//- @jadedoc
examples:
- >
+myMixin({
foo: 'foo
}
Locals
Jade locals can be also be passed.
//- @jadedoc
name: tag
locals:
foo: foo
div #{foo}
Reserved words
arguments
for mixin arguments.attributes
for (mixin) attributes.locals
for template locals.examples
for example mixin calls
How to use
npm install jade-doc
var jadeDoc = require('jade-doc');
jadeDoc({
input: '**/*.jade',
output: 'anything.json'
});
Command line
Optionally use it through the command line.
jade-doc input.jade
jade-doc input.jade --output output.json
jade-doc "**/*.jade" --output output.json
Output file
Output will look something like this.
[
{
"meta": {
"name": "foo",
"description": "foo description"
},
"file": "file.jade",
"source": "// foo",
"output": "<!-- foo-->"
}
]