mox

A documentation to markdown creator

mox

A markdown javascript documentation generator

var mox = require("mox");
 
var source = "./source1.js";
 
mox.run(source1).pipe(process.stdout)
=> //outputs markdown data 

This project allows extended flexiblity in generating markdown documentation for javascript projects. The advantage of this project over others is:

  • Allows you to easily create a table of contents of methods, declarations, categories, source file names
  • Allows you to group your code using the @category tag
  • Allows you to group your code using the source file name

It was inspired by the lodash documentation.

Mox generates source documentation based on jsdoc and dox. For information on how to document your source see the following:

Mox templates use jade as the templating engine. To create custom templates see jade documentation for reference

npm install mox

See the examples directory for ouput using the predefined mox templates:

examples

var fs = require("fs");
var mox = require("../lib/mox");
 
var source1 = "./source1.js";
var fileWriteStream = fs.createWriteStream("./someOutputfile.md")
 
 
mox.run([source1]).pipe(fileWriteStream);
 
=> //markdown documentation file will be generated to output directory 

All below options are available to mox

var allMoxOptions = {
name : "someProjectName", //-> name of the project or application being documented 
 
version : "aVersion", //-> documentation or project version number 
 
moxFile : "mox object json output file",
 
htmlFile : "htmlFile" //-> html generated output file path, 
 
outputFile : "./someOutputFile.md", //-> mark down documentation output file, 
 
template : "moxTemplateName | ./someCustomTemplate.jade", //-> mox template name or custom template to use 
}
var fs = require("fs");
var mox = require("../lib/mox");
 
var source1 = "./source1.js";
var source2 = "./source2.js";
var fileWriteStream = fs.createWriteStream("./someOutputfile.md")
 
 
mox.run([source1,source2]).pipe(fileWriteStream);
 
=> //markdown documentation file will be generated to output directory 
var fs = require("fs");
var mox = require("../lib/mox");
 
var source1 = "./source1.js";
var fileWriteStream = fs.createWriteStream("./someOutputfile.md")
 
mox.run(source1,{template:"category"}).pipe(fileWriteStream);
=> //markdown documentation file will be generated to output directory 
var fs = require("fs");
var mox = require("../lib/mox");
 
var source1 = "./source1.js";
var fileWriteStream = fs.createWriteStream("./someOutputfile.md")
 
mox.run(source1,{template:"file"}).pipe(fileWriteStream);
=> //markdown documentation file will be generated to output directory 
var fs = require("fs");
var mox = require("../lib/mox");
 
var source1 = "./source1.js";
var fileWriteStream = fs.createWriteStream("./someOutputfile.md")
 
mox.run(source1,{markdown:"gfm"}).pipe(fileWriteStream);
=> //markdown documentation file will be generated through file stream 

A custom template can be created. All templates must be created using jade. See jade documentation for details on how to use jade. The jade template will have access to the mox object.

Sample Custom template(customTemplate.jade)

doctype 5
html
body
h2 Application Objects, Functions, Declarations
ul
each comment in mox
li
a(href="##{comment.name.toLowerCase()}")= comment.name
h2 Application Objects, Functions, Declarations
each comment in mox
h3= comment.name
p!= comment.description.body

Here is how to use the custom template in mox

var fs = require("fs");
var mox = require("../lib/mox");
 
var source1 = "./source1.js";
var fileWriteStream = fs.createWriteStream("./someOutputfile.md")
 
mox.run(source1, //->source files to generate documentation for 
{template:'./customTemplate.jade'}) //->specfies path to custom template 
.pipe(fileWriteStream); 
=> //markdown documentation file will be created to file stream 
var mox = require("../lib/mox");
 
var source1 = "./source1.js";
var source2 = "./source2.js";
var options = {
outputFile :"./someOutputfile.md" //->output markdown file 
};
 
mox.run([source1,source2], //->source files to generate documentation for 
options); 
=> //markdown documentation file will be created to output directory 

Markdown documentation will be returned if a callback is specfied as the last argument

var mox = require("../lib/mox");
 
var source1 = "./source1.js";
var source2 = "./source2.js";
 
var options = {
outputFile :"./someOutputfile.md", //->output markdown file 
template:'category' //-> Using category template 
};
 
mox.run([source1,source2], //->source files to generate documentation for 
options, //-> Mox options 
function(error,markdownDocumentation){}); //->markdownDocumentation equals the markdown file contents 
=> //markdown documentation file will be created to output directory 

Mox uses dox to generate all documentation comments. All dox comments will be available to use in a template.

Here is the object that gets created and is available to all templates:

{
mox : moxComments, //-> mox generated comments 
 
comments : allSourceComments, //-> generated dox comments 
 
files : files, //-> mox generated comments grouped by source filename 
//-> {tag: "nameOfile", 
//->  comment : **GeneratedMoxCommentObject**} 
 
categories : categories, //-> mox generated comments grouped by **@categoy** tag 
//-> {tag: "nameOfCategory", 
//->  comment : **GeneratedMoxCommentObject**} 
}
 

The mox generated comments are subset of dox comments that allow for grouping and additional data

/**
 * A Class description
 *
 * Example:
 * 
 * ```javascript
 * SomeClass.someClassMethod(x);
 * ```
 *
 * @author Tim Chaplin
 * @category SomeClassCategory
 * @class SomeClass
 * @constructor
 * @param {String} param a parameter
 * @optional
 */
function SomeClass(){}

Generates mox object:

[ 
{ 
params: [ 
{
types: ['Function', 'String'],
name : "paramName",
description : "description"
}],
name: 'SomeClass',
type: 'function',
fileName: 'someFileName.js',
description: 
{ 
full: '<p>A Class description</p>\n\n<p>Example:</p>\n\n<div class="highlight"><pre lang="javascript">SomeClass. someClassMethod(x);\n</pre></div>',
summary: '<p>A Class description</p>',
body: '<p>Example:</p>\n\n<div class="highlight"><pre lang="javascript">SomeClass.someClassMethod(x);\n</pre></div>' 
},
author: 'Tim Chaplin',
category: 'SomeClassCategory',
class: 'SomeClass',
constructor: true,
optional: true
}
]
function SomeClass(){
/**
 * SomeClassFunction
   *
   * Example:
   *
   * ```javascript
   * SomeClass.someClassMethod(x);
   * ```
 * @category SomeClassCategory
 * @method someClassMethod
 * @param {Function|String} methodParam some method param
 * @return {Function|String} A return value
 * @chainable
**/
self.someClassMethod = function(methodParam) {
self.lib.Plugins.loadPlugin(self, pluginPath);
return self;
};
}

Generates mox object:

[ 
{ 
params: { 
[{
    types: ['Function', 'String'],
    name : "paramName",
    description : "description"
    }],
name: 'someClassMethod',
type: 'method',
fileName: 'someFileName.js',
description: 
{ 
full: '<p>SomeClassFunction</p>\n\n<p>Example:</p>\n\n<div class="highlight"><pre lang="javascript">SomeClass.someClassMethod(x);\n</pre></div>',
summary: '<p>SomeClassFunction</p>',
body: '<p>Example:</p>\n\n<div class="highlight"><pre lang="javascript">SomeClass.someClassMethod(x);\n</pre></div>' 
},
category: 'SomeClassCategory',
method: 'someClassMethod',
return: { types: [Object], description: 'A return value' },
chainable: true 
}
]
/** Some property Thing */
var aProperty = "someProperty";

Generates mox object:

[ 
  { 
params: [],
name: 'aProperty',
type: 'declaration',
fileName: 'someFileName.js',
description: 
{ 
full: '<p>Some property Thing</p>',
summary: '<p>Some property Thing</p>',
body: '' 
} 
   }
]
/** 
 * Some property with type description
 * @type {String}
 */
var aPropertyWithType = "somePropertyWithType";

Generates mox object:

{
    "params": [],
    "name": "aPropertyWithType",
    "type": {
        "types": [
            "String"
        ]
    },
    "fileName": "./tests/fixtures/functionSomeClass.js",
    "description": {
        "full": "<p>Some property with type description</p>",
        "summary": "<p>Some property with type description</p>",
        "body": ""
    },
    "category": "SomeClassCategory"
}

Thanks to the following frameworks used as dependcies for the project

  • dox - For getting jsdoc style documention object
  • Jade- For templating
  • hammerdown - Streaming HTML to markdown

Other markdown javascript documentation projects