# mox

> A documentation to markdown creator

Latest version **0.0.16** (published 2015-01-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install mox
pnpm add mox
yarn add mox
bun add mox
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.16 |
| Published | 2015-01-24 |
| First published | 2013-08-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 0.10 |
| Dependencies | 8 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 20 |
| Author | Tim Chaplin |
| Maintainers | tjchaplin |
| Keywords | mox, dox, markdown, md, documentation, generator, template |

## Links

- npm: https://www.npmjs.com/package/mox
- Repository: https://github.com/tjchaplin/mox
- Homepage: https://github.com/tjchaplin/mox.git
- Issues: https://github.com/tjchaplin/mox/issues
- npm.io page: https://npm.io/package/mox

## Dependencies (8)

- [dox](https://npm.io/package/dox.md) ~0.5.3
- [jade](https://npm.io/package/jade.md) ~1.9.1
- [through](https://npm.io/package/through.md) ~2.3.6
- [fs.extra](https://npm.io/package/fs.extra.md) ~1.3.2
- [node-dir](https://npm.io/package/node-dir.md) ~0.1.6
- [hammerdown](https://npm.io/package/hammerdown.md) 1.0.1
- [yaenumerable](https://npm.io/package/yaenumerable.md) ~1.0.1
- [concat-stream](https://npm.io/package/concat-stream.md) ~1.4.7

## Alternatives

- [@mdxeditor/editor](https://npm.io/package/@mdxeditor/editor.md) — 962.4K weekly downloads
- [mmdb-lib](https://npm.io/package/mmdb-lib.md) — 680.9K weekly downloads
- [playcanvas](https://npm.io/package/playcanvas.md) — 36.2K weekly downloads
- [@glw907/cairn-cms](https://npm.io/package/@glw907/cairn-cms.md) — 967 weekly downloads
- [markdown-to-confluence](https://npm.io/package/markdown-to-confluence.md) — 103 weekly downloads

## Recent versions

- 0.0.16 (latest) — 2015-01-24
- 0.0.14 — 2014-04-13
- 0.0.13 — 2014-04-13
- 0.0.12 — 2014-04-12
- 0.0.11 — 2014-02-15
- 0.0.10 — 2014-02-15
- 0.0.9 — 2014-02-14
- 0.0.8 — 2013-08-19
- 0.0.7 — 2013-08-19
- 0.0.6 — 2013-08-19
- 0.0.5 — 2013-08-19
- 0.0.4 — 2013-08-18
- 0.0.3 — 2013-08-18
- 0.0.2 — 2013-08-18
- 0.0.1 — 2013-08-18

## README

mox
===

A markdown javascript documentation generator

[![Build Status](https://travis-ci.org/tjchaplin/mox.png)](https://travis-ci.org/tjchaplin/mox)

### Get Going

```javascript
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](https://github.com/bestiejs/lodash/blob/master/doc/README.md).

Mox generates source documentation based on [jsdoc](http://usejsdoc.org/) and [dox](https://github.com/visionmedia/dox). For information on how to document your source see the following:
* [Use JsDoc Reference](http://usejsdoc.org/)
* [Dox reference](https://github.com/visionmedia/dox)

Mox templates use [jade](http://jade-lang.com/) as the templating engine.  To create custom templates see [jade documentation](http://jade-lang.com/reference/) for reference

## Install

```
npm install mox
```

## Example output

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

[`examples`](https://github.com/tjchaplin/mox/tree/master/doc/)

## How to use

### Default Template

```javascript
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
```

### Options

All below options are available to mox

```javascript
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
}
```

### Default Template With Multiple Sources

```javascript
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
```

### Categroy Template

```javascript
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
```

### File Template

```javascript
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
```

### Default Template with Github Flavored Markdown(gfm)

```javascript
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
```

### Custom Template

A custom template can be created.  All templates must be created using jade.  See [jade documentation](http://jade-lang.com/reference/) for details on how to use jade.  The jade template will have access to the [mox](#mox-generated-comments) object.

Sample Custom template(customTemplate.jade)
```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

```javascript
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
```

### Default Template with outputfile

```javascript
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
```

### Asynchronus results

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

```javascript
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
```

## What gets generated

Mox uses [dox](https://github.com/visionmedia/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:

```javascript
{
	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**}
}

```

### Mox generated comments

The mox generated comments are subset of [dox](https://github.com/visionmedia/dox) comments that allow for grouping and additional data

####Given class

```javascript
/**
 * 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:

```javascript
[ 
	{ 
		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

```javascript
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:

```javascript
[ 
	{ 
		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

```javascript
/** Some property Thing */
var aProperty = "someProperty";
```

Generates mox object:

```javascript
[ 
  { 
	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

```javascript
/** 
 * Some property with type description
 * @type {String}
 */
var aPropertyWithType = "somePropertyWithType";
```

Generates mox object:

```javascript
{
    "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](https://github.com/visionmedia/dox) - For getting jsdoc style documention object
* [Jade](http://jade-lang.com/ )- For templating
* [hammerdown](https://github.com/tjchaplin/hammerdown) - Streaming HTML to markdown

Other markdown javascript documentation projects
* [Markdox](http://cbou.github.io/markdox/)
* [jsdox](http://jsdox.org/)

---
_Source: https://npm.io/package/mox · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._