Mocoolka-docs

Overview

Create a single page documentation site for your node.js module using a set of documentation source files including markdown and JSDoc annotated JavaScript.

Install

npm install mocoolka-docs -g

Getting Started

Create a set of markdown files in a directory. Each markdown file should follow the basic docs markdown conventions. In order to parse a set of content, mocoolka-docs requires a docs.json config file. Here is a simple example:

docs.json

{
  "content": [
    "README.md",
    "docs/overview.md",
    "docs/guides.md",
    "docs/api.md",
    "lib/foo.js",
    "lib/bar.js"
  ]
}

This config file should specify every documentation source file you wish to be included in your site generation.

Building

To build a static html version of your doc site run the mocoolka docs cli in your project directory or specify the path to your docs.json config. The --out argument is required.

# in the same directory as docs.json 
$ mdocs --out my-doc-site
 
# or specify the path to your config 
$ mdocs --config path/to/my/docs.json --out my-doc-site

Preview

To preview your docs while editing run the mocoolka docs cli with the --preview argument. This will start a server that builds and renders your doc site every time you refresh your browser.

# start the preview server 
$ mdocs --preview
 
# specify a port (default: 3000) 
$ mdocs --preview --port 8080

Sections

Each file read by mocoolka-docs (markdown, or JavaScript) is parsed into a set of nested sections. The parser relies on the file being formated using the markdown or JavaScript conventions.

Since the output of mocoolka-docs is a single html page, the input (markdown or JavaScript) is treated as a single page before parsing. This means that you can organize your docs into multiple files, but must be aware that references (links, names, etc) will all be global.

Section Depth

Markdown

Each section parsed from markdown has a specified depth. Markdown file's section depth is determined by the type of header the parser finds. In markdown the ## foo header is parsed as <h2>foo</h2> with a depth of 2.

JavaScript

JavaScript annotation sections all have the same preset depth. This value can be changed using the ``

Injecting Sections

You may add sections that were not discovered by parsing your documentation files using the content config setting. Here is an example that adds a header and section to each js file.

[
  "docs/overview.md",
  "docs/guides.md",
  "docs/api.md",
  {"title": "Foo API", "depth": 2},
  "lib/foo.js",
  {"title": "Bar API", "depth": 2},
  "lib/bar.js"
]

The depth attribute of the section object will set the sections depth and navigation header style.

Documentation Source Files

Mocoolka-docs requires a list of files to use for generating your documentation site. This list may contain markdown files, JavaScript files, and section objects.

Mocoolka-docs can parse markdown and dox style JavaScript. Mocoolka-docs is fairly good at determining your intended structure. Following the conventions below will ensure your docs site is compatible with mocoolka-docs.

Markdown Conventions

Mocoolka-docs uses Github Flavored Markdown for parsing its markdown as well as generating section anchors.

Sections

To create a section you only need to provide a markdown header eg. # or ###. The following example creates several sections.

# My Section

This is a paragraph.

## Sub Section

This is a paragraph within a sub section.

The first section # My Section will have a depth of 1 and the second's depth will be 2. See (section depth)[#section-depth] for more info.

Links / Anchors

Each section gets its own unique anchor. The title of the section is turned into a url compatible string. Here are a couple examples.

header                 anchor
# Foo Bar              #foo-bar
# foo/bar              #foobar
# foobar               #foobar-1

If an anchor already exists, a number will be added to the end to ensure it is unique.

Static Code

Both Github Flavored Markdown and normal markdown code samples are supported. To enable syntax highlighting explicitely specify the language like the example below. Syntax highlighting uses highlight.js. See a list of supported languages here;

```javascript
var a = b + c;
```

Auto Code

Check auto code file when build doc for every method ,auto code will add to doc if exist. Add auto code file step

• Create examples Directory on root path
• Create sub directory that directory name is same as javascript filename
• Create example code file that file name is same as method name

Images

Mocoolka-docs supports linking to images absolutely (using regular markdown):

![Alt text](http://foo.com/path/to/img.jpg)
![Alt text](http://foo.com/path/to/img.jpg "Optional title")

Or you can bundled your images with your site using the assets setting.

{
  "content": [...],
  "assets": "path/to/assets"
}

Now any image can be referenced like this:

![Alt text](assets/img.jpg)

JavaScript Conventions

Annotations

Mocoolka-docs will parse .js files for JSDoc annotations using the dox parser.

Annotation may contain markdown. This markdown will be rendered as HTML but will not be parsed for sections. Here is a basic example.

/**
 * Escape the given `html`.
 *
 * **Example:**
 *
 *     utils.escape('<script></script>')
 *     // => '&lt;script&gt;&lt;/script&gt;'
 *
 * @param {String} html The string to be escaped
 * @return {String} 
 */
 
exports.escape = function(html){
  return String(html)
    .replace(/&(?!\w+;)/g, '&amp;')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;');
};

See the JSDoc site for more examples.

Auto Static Annotations

To add an annotation static if code begin with static

/*
 * My ignored annotation example...
 *
 * @myparam My value...
 */
 Class MyClass{
    /**
    * my static method
    */
     static myMethod(){
     }
 }

Ignoring Annotations

To ignore an annotation change the comment block from /** to /*!.

/*!
 * My ignored annotation example...
 *
 * @myparam My value...
 */
 
// ...

You can also use the @private attribute to prevent your annotation from being rendered in your doc site.

/**
 * My private annotation example...
 *
 * @myparam My value...
 * @private
 */
 
// ...

Sections

Sections are created for each JSDoc annotation. If you want to further organize your api docs you can inject sections using the "content" config setting. Here is an example.

Links / Anchors

Each annotation gets its own unique anchor. The title of the annotation is turned into a url compatible string. Here are a couple examples. Note: anything in parenthesis will be removed.

header                 anchor
# app.get(foo, bar)    #app.get
# app.get()            #app.get-1

Config

The following is a list of configuration properties for mocoolka-docs. You may specify these values as a docs.json file or as an Object using the node.js api.

Available Options

• title - the title of your documentation site
• version - the version of the project you are documenting
• content - default: 'content' - specify your documentation source files
• codeSectionDepth - default 4 - specify the depth of JavaScript sections
• assets - path to your assets directory

Content

Documentation will be rendered in the order it is listed in the content array. Below is an example content array with markdown, JavaScript, and an injected section.

[
  "docs/overview.md",
  "docs/guides.md",
  "docs/api.md",
  {"title": "API", "depth": 2},
  "lib/foo.js",
  "lib/bar.js"
]

Glob patterns are supported for the items.

[
    "docs/overview.md",
    "docs/guides.md",
    "docs/api.md",
    {"title": "API", "depth": 2},
    "lib/*.js"
]

In the example above, the order of top-level items is still honored while files matching the wildcard are sorted.

Assets

Bundle a set of files, such as images, with your documentation. This directory will be copied recursively into your doc site as site/assets. The name will not be preserved.

Link to these files from your docs like this:

![Alt text](assets/img.jpg)
[My File](assets/pkg.zip)

JSDoc Annotations

Supported annnotations

• class
• constructor
• ignore
• instance
• method
• module
• param
• private
• property
• public
• return
• static

Not supported

• author
• abstract
• access
• alias
• augments
• borrows
• constant
• constructs
• copyright
• default
• desc
• deprecated
• enum
• event
• example
• exports
• external
• fires
• global
• inner
• kind
• lends
• license
• link
• member
• mixes
• mixin
• namespace
• name
• overview
• memberof
• protected
• readonly
• requires
• see
• since
• summary
• this
• throws
• todo
• tutorial
• type
• typedef
• variation
• version

Mocoolka annnotations

Promise

The may add @param below@resolve tag and @reject tag.

The @resolve tag and @reject tag auto add type Function,ignore annotation type

Syntax: @resolve [resolve object desc] @reject [reject object desc]

/**
 * Function to test a standalone promise.
 *
 * @param {Array} An array parameter.
 * @return {Promise}
 * @resolve   A sample resolve .
 * @param {Object} first -resolve first param
 * @propertyDetail {string} value1name -value1name description
 * @propertyDetail {string} value1value -value1value description
 * @param {Object} [second] -resolve second param
 * @propertyDetail {string} value2name -value2name description
 * @propertyDetail {string} value2value -value2value description
 * @reject   An error object
 */
function promiseStandalone(arg) {

}

propertyDetail

The annnotation comment the param property resolve reject return staticProperty when parent annotation type is Object

Syntax: @propertyDetail [{Types}] name [-desc]

/**
 * Function to test a standalone promise.
 *
 * @param {Array} An array parameter.
 * @return {Promise}
 * @resolve {Object}  A sample resolve .
 * @propertyDetail {string} root -root path
 * @reject {Object}  An error object
 */
function promiseStandalone(arg) {

}

staticProperty

The annotation comment the static property Syntax: @see property

callback

The @callback tag provides information about a callback function that can be passed to other functions.

The may add @param below @callback.

The @callback tag auto add type Function,ignore annotation type

Syntax: @callback name [-desc]`

  /**
   * iterator Object or array
   * @param {Object|Array} obj
   * @callback  callback -return item when input is Array ,return object{key:key,value:obj[key] when
   * input is object
   * @param {Object} item -item in object
   * @propertyDetail {string} key -item key
   * @propertyDetail {Object} value -item value
   */
  static iterator  (obj, callback) {
  }