mocoolka-docs
v0.5.8
Published
documentation site generator
Downloads
4
Readme
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>')
* // => '<script></script>'
*
* @param {String} html The string to be escaped
* @return {String}
*/
exports.escape = function(html){
return String(html)
.replace(/&(?!\w+;)/g, '&')
.replace(/</g, '<')
.replace(/>/g, '>');
};
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) {
}