Pug-doc

Pug-doc is a Pug documentation generator. It takes Pug files as input, looks for comments flagged with @pugdoc and puts its contents in an output JSON file. It looks for the immediate next pug code block for output.

> This package does not provide a styled interface for the documentation itself. Use Discodip for HTML output of all the examples, which can be used however you like.

> You could also use pug-doc-html or pug-doc-markdown for human readable docs. Optionally use pug-doc-faucet for prettier terminal reporting.

Usage

Use the keyword @pugdoc to flag unbuffered block comments inside your pug files. Comments should be written in properly formatted YAML format.

``pug
//- @pugdoc
name: my pugdoc
description: this is a description for my pug doc
beep: boop
foo: faa
`

see test/fixtures for examples.

---

$3

The immediate next Pug code block after the comment will be compiled to HTML output. If you need to capture multiple blocks, see Capture multiple blocks

`pug
//- @pugdoc
name: some-node

div.this-is-output-for-pug-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.

`pug
//- @pugdoc
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')
-
name: My mixin
description: this is my subexample
examples:
- |
+myMixin('beep', 3)

mixin myMixin(arg1, arg2)
div this is a mixin #{arg1} #{arg2} #{attr1} #{attr2}
`

---

#### Examples
You can add an example or multiple examples with the example or examples keyword, where the former is a YAML string and the latter a YAML list. The block flag will be replaced by the captured block.

For documenting mixins the use of examples is recommended, since mixins will not be executed if no examples are given. For other pug blocks, examples are optional and can be used to add extra context (e.g. a parent div with styling).

_single example_
`pug
//- @pugdoc
name: example
example: |
div.example(style="max-width: 300px")
block

p this is my example
`

_unnamed examples_
`pug
//- @pugdoc
name: example
examples:
- |
div.example
block
- |
div.example
block

p this is my example
`

If an object is found inside the examples list, two things will happen. The subexample is 1) rendered and appended to the rest of the examples and 2) added to a list of fragments. This way a complete, rendered HTML example will be available, while also keeping the named subexamples intact.

_named examples and combined example_
`pug
//- @pugdoc
name: example
examples:
-
name: Subexample 1
example: |
div.example1
block
-
name: Subexample 2
example: |
div.example2
block

p this is my example
`

The behavior of combining examples into 1 can be turned of by setting example: false.

_only named examples_
`pug
//- @pugdoc
name: example
example: false
examples:
-
name: Subexample 1
example: |
div.example1
block
-
name: Subexample 2
example: |
div.example2
block

p this is my example
`

_beforeEach_
`pug
//- @pugdoc
name: example
beforeEach: |
include ./my-mixin
examples:
-
name: Example 1
example: +my-mixin(1)
-
name: Example 2
example: +my-mixin(2)
-
name: Example 2
beforeEach:
example: +my-mixin(3) // ‹- error: my-mixin is undefined
`


---

#### Locals
Pug locals can be also be passed.

`pug
//- @pugdoc
name: tag
locals:
foo: foo

div #{foo}
`

---

#### Capture multiple blocks
The capture keyword specifies how many blocks after the comment will be returned. Use capture: all to capture the rest of the document. Use capture: section to capture all items until the next pugdoc tag.

`pug
//- @pugdoc
name: tag
capture: 3

div 1
div 2
div 3
div nope
div nope
`

---

#### Keywords
* name used as an id
* description provide context
* arguments for mixin arguments.
* attributes for (mixin) attributes.
* locals for template locals.
* beforeEach (string) add pug code before each example
* afterEach (string) add pug code after each example
* example
- (string) for example mixin call or example block, or
- (false) to prevent rendering of master example combining all examples
* examples (list) for example mixin calls or example blocks
* examples.name
* examples.description
* examples.example (string)
* examples.examples (list)
* examples.beforeEach (string) overwrite beforeEach for single example
* examples.afterEach (string) overwrite afterEach for single example
* capture for the number of code blocks to be captured
- all: the rest of the document until it meets a lower indent
- section: the rest of the document until it meets a lower indent or a new pugdoc comment
- number: the exact positive number of blocks

---

How to use


npm install pug-doc

`js
const pugDoc = require('pug-doc');

pugDoc({
input: '*/.pug',
output: 'anything.json',
complete: function(){},
locals: {
myTemplateLocal: 'foo'
}
});
`

---

Caveats

$3

Mixins are standalone blocks, so you need to include any dependencies inside the mixin.

`pug
include ../mixin1.pug

//- @pugdoc
name: mixin2
example: +mixin2

mixin mixin2
+mixin1
`

Will throw something like TypeError: pug_mixins.mixin1 is not a function on line x. Instead you need to do the include inside the mixin,

`pug
mixin mixin2
include ../mixin1.pug
+mixin1
+mixin2
`

or include it inside the example

`pug
//- @pugdoc
name: mixin2
example: |
include ../mixin1.pug
+mixin2

mixin mixin2
+mixin1
`

---




$3

Optionally use it through the command line.

`bash
pug-doc input.pug
`

`bash
pug-doc input.pug --output output.json
pug-doc "*/.pug" --output output.json
`




$3

Output will look something like this.

`json
[
{
"meta": {
"name": "foo",
"description": "foo description"
},
"file": "file.pug",
"source": "// foo",
"output": ""
}
]
``