doxdox

JSDoc to Markdown, Bootstrap, and custom Handlebars template documentation generator.

doxdox is a simple to use documentation generator that takes JSDoc comment blocks and generates different documentation formats; Markdown, Bootstrap, and custom Handlebars templates.

doxdox also features support for extendability via custom plugins for both parsing and generating documentation.

In

/**
 * Parse array of directory globs and/or files, and then render the parsed data through the defined layout plugin.
 *
 *     parseInputs(['src/*.js'], {'ignore': [], 'parser': 'dox', 'layout': 'markdown'}).then(content => {});
 *
 * @param {Array} inputs Array of directory globs and/or files.
 * @param {Object} config Configuration object.
 * @param {String} config.ignore Array of paths to ignore.
 * @param {String} config.parser String representing the parser to be used.
 * @param {String} config.layout String representing the layout plugin to be used.
 * @return {Object} Promise
 * @public
 */

Out

Bootstrap template plugin, included with doxdox https://github.com/neogeek/doxdox-plugin-bootstrap

Getting Started

The following instructions assume you have already setup JSDoc comment blocks in your codebase. If you have not and would like to learn more about how to use JSDoc, visit http://usejsdoc.org/.

First install doxdox globally with NPM.

$ npm install doxdox -g

Then, once you have doxdox installed globally (or local to your project, see below), you can start generating documentation. For this example, we will be generating a Markdown file and storing it within the project.

With a directory structure similar to the example shown below, run the following command to generate a Markdown file and output the generated contents to a new file named DOCUMENTATION.md.

$ doxdox 'lib/**/*.js' --layout markdown --output DOCUMENTATION.md

├─ bin/
├─ coverage/
├─ lib/
│   ├─ doxdox.js
│   ├─ loaders.js
│   └─ utils.js
├─ node_modules/
└─ test/
     ├─ fixtures/
     └─ specs/
          ├─ doxdox.js
          ├─ loaders.js
          └─ utils.js

Installation

doxdox can be installed via either NPM or Yarn.

$ npm install doxdox -g

$ yarn global add doxdox

Usage

CLI

Layouts

Markdown

For more information on Markdown visit http://daringfireball.net/projects/markdown/.

$ doxdox 'lib/**/*.js' --layout markdown --output DOCUMENTATION.md

Bootstrap

Form more information on Bootstrap visit https://v4-alpha.getbootstrap.com/.

$ doxdox 'lib/**/*.js' --layout bootstrap --output docs/index.html

Custom Handlebars Template

For more information on writing Handlebars templates visit http://handlebarsjs.com/.

$ doxdox 'lib/**/*.js' --layout templates/README.hbs --output README.md

Ignore

The ignore flag allows you to ignore both directories (with glob syntax) and files. Comma separated values.

$ doxdox './**/*.js' --ignore './coverage/**/*.js'

See https://github.com/isaacs/minimatch#usage for more information on how to use globs.

Help

Usage: doxdox <path> ... [options]

Options:

 -h, --help             Display this help message.
 -v, --version          Display the current installed version.
 -d, --description      Sets description.
 -i, --ignore           Comma separated list of paths to ignore.
 -l, --layout           Template to render the documentation with.
 -o, --output           File to save documentation to. Defaults to stdout.
 -p, --package          Sets location of package.json file.
 -t, --title            Sets title.

Included Layouts:

 - Markdown (default)    (http://daringfireball.net/projects/markdown/)
 - Bootstrap             (http://getbootstrap.com/)
 - Handlebars            (http://handlebarsjs.com/)

NPM Run Scripts

For more information on NPM run scripts visit https://docs.npmjs.com/cli/run-script.

$ npm install doxdox --save-dev

{
  "devDependencies": {
    "doxdox": "2.0.1"
  },
  "scripts": {
    "docs": "doxdox 'lib/**/*.js' --layout markdown --output DOCUMENTATION.md"
  }
}

$ npm run docs

Via JavaScript

const doxdox = require('doxdox');

parseInputs(['lib/**/*.js'], {
    'parser': 'dox',
    'layout': 'markdown'
}).then(content => {

    process.stdout.write(content);

});

See documentation for more information on parseInputs.

Packages

Core Packages

All core packages come pre-installed with doxdox.

| Package | Version | Dependencies | Documentation | | ------- | ------- | ------------ | ------------- | | doxdox-parser-dox | | | | | doxdox-plugin-bootstrap | | | | | doxdox-plugin-handlebars | | | | | doxdox-plugin-markdown | | | |

• doxdox-parser-dox - 🔌 Dox parser plugin for doxdox.
• doxdox-plugin-bootstrap - 🔌 Bootstrap template plugin for doxdox.
• doxdox-plugin-handlebars - 🔌 Custom Handlebars template plugin for doxdox.
• doxdox-plugin-markdown - 🔌 Markdown template plugin for doxdox.

Other Packages

Non-core packages must be installed separately from doxdox.

$ npm install doxdox doxdox-plugin-dash --save-dev

The, via the --layout flag, you specify the plugin name minus doxdox-plugin-.

| Package | Version | Dependencies | Documentation | | ------- | ------- | ------------ | ------------- | | doxdox-plugin-dash | | | | | doxdox-plugin-github-wiki | | | | | grunt-doxdox | | | |

• doxdox-plugin-dash - 🔌 Dash export plugin for doxdox.
• doxdox-plugin-github-wiki - 🔌 GitHub wiki export plugin for doxdox.
• grunt-doxdox - Grunt plugin for doxdox.

Questions

If you have any questions regarding the use of doxdox, please use either the Gitter chat room or Stack Overflow. The issue tracker is to be used for bug reports and feature requests only.

Contributing

Be sure to review the Contributing Guidelines before logging an issue or making a pull request.

License

MIT