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 

##Purpose

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

####Given class

/**
 * 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
    }
]

####Given Method

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

####Given Declaration

/** 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: '' 
    } 
   }
]

####Given Property with type

/** 
 * 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"
}

##Credits/Other Frameworks

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