jade-doc

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-->"
  }
]