Doxdox

⚠️ Notice: This repository is undergoing a massive rewrite. Things will be missing, broken, or incomplete as development continues.

Documentation, simple.

doxdox is a simple to use documentation generator that takes JSDoc comment blocks and generates different documentation formats; Markdown, Bootstrap, GitHub Wiki, and other custom plugins.

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

Example

In

/**
 * Request content from URL or array of URLs.
 *
 * @example fetch('http://www.google.com/humans.txt').then(content => console.log(content));
 * @example fetch(['http://www.google.com/humans.txt']).then(contents => console.log(content[0]));
 * @param {String|String[]} urls A URL or an array of URL strings.
 * @param {Object} [options] Options object.
 * @param {String} [options.cacheDirectory] Directory to store cache. Default is `temp/cache/`.
 * @param {Object} [options.requestOptions] Custom request options object. Default is `{}`.
 * @param {Number} [options.ttl] TTL (Time to live) in seconds. Default is 1800
 * @return {Promise<String[]>} Contents of request as an array.
 * @public
 */

Out

Install

Globally

$ npm install doxdox-cli@v4.0.0-preview.25 -g

Locally

$ npm install doxdox-cli@v4.0.0-preview.25 --save-dev

Usage

CLI

$ doxdox '**/*.js'

Custom Meta Information

Name

$ doxdox '**/*.js' --name "doxdox-next"

Description

$ doxdox '**/*.js' --description "Preview release of the doxdox package"

Ignore

Files can be ignored via the command line.

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

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

They can also be ignored via a .doxdoxignore file. This file is similar in format to .gitignore and .npmignore.

tests/**/*.js
**/*.test.js

Output

File

$ doxdox '**/*.js' --output docs.md

Stdout

$ doxdox '**/*.js' > docs.md

Renderers

Markdown

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

$ doxdox '**/*.js' --renderer markdown --output docs.md

Bootstrap

For more information on Bootstrap visit https://getbootstrap.com.

$ doxdox '**/*.js' --renderer bootstrap --output docs.html

JSON

$ doxdox '**/*.js' --renderer json --output docs.json

Help

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

Options:

 -h, --help             Display this help message.
 -v, --version          Display the current installed version.
 -n, --name             Sets name of project.
 -d, --description      Sets description of project.
 -i, --ignore           Comma separated list of paths to ignore.
 -l, --parser           Parser used to parse the source files with. Defaults to jsdoc.
 -r, --renderer         Renderer to generate the documentation with. Defaults to Markdown.
 -o, --output           File to save documentation to. Defaults to stdout.
 -p, --package          Sets location of package.json file.

Included Layouts:

 - Markdown (default)    (https://daringfireball.net/projects/markdown)
 - Bootstrap             (https://getbootstrap.com)
 - JSON

NPM Run Scripts

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

$ npm install doxdox-cli@v4.0.0-preview.25 --save-dev

{
  "devDependencies": {
    "doxdox": "4.0.0-preview.14"
  },
  "scripts": {
    "docs": "doxdox 'lib/**/*.js' --renderer markdown --output DOCUMENTATION.md"
  }
}

$ npm run docs

JavaScript

Note: To use doxdox in this way you must add "type": "module" to your package.json file.

import doxdox from 'doxdox';

import parser from 'doxdox-parser-jsdoc';

import renderer from 'doxdox-renderer-markdown';

doxdox(
  process.cwd(),
  ['lib/index.js', 'lib/loaders.js', 'lib/utils.js'],
  parser,
  renderer,
  {
    name: 'doxdox-example',
    description: 'Description of doxdox example.'
  }
).then(output => {
  process.stdout.write(output);
});

Next.js

Note: To use doxdox in this way you must add "type": "module" to your package.json file.

import type { NextPage } from 'next';

import doxdox from 'doxdox';

import parser from 'doxdox-parser-jsdoc';

import renderer from 'doxdox-renderer-bootstrap';

export const getServerSideProps = async () => {
  const docs = await doxdox(
    process.cwd(),
    ['lib/index.js', 'lib/loaders.js', 'lib/utils.js'],
    parser,
    renderer,
    {
      name: 'doxdox-example',
      description: 'Description of doxdox example.'
    }
  );

  return { props: { docs } };
};

const Docs: NextPage<{
  docs: string;
}> = ({ docs }) => {
  return <div dangerouslySetInnerHTML={{ __html: docs }}></div>;
};

export default Docs;

Custom Renderer

Note: To use doxdox in this way you must add "type": "module" to your package.json file.

export default async doc => JSON.stringify(doc);

doxdox -r renderer.js

Plugins

Parsers

Default Parsers

The following parsers are bundled with doxdox.

| Name | Description | Version | | ------------------------------------------------------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | doxdox-parser-jsdoc | JSDoc parser for doxdox. | |

A template for creating your own parser doxdox-parser-template.

Optional Parsers

The following parsers are not bundled with doxdox and must be installed separately.

| Name | Description | Version | | -------------------------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | doxdox-parser-dox | dox parser for doxdox. | |

Renderers

Default Renderers

The following renderers are bundled with doxdox.

| Name | Description | Version | | ------------------------------------------------------------------ | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | | doxdox-renderer-bootstrap | Bootstrap renderer for doxdox. | | | doxdox-renderer-json | JSON renderer for doxdox. | | | doxdox-renderer-markdown | Markdown renderer for doxdox. | |

A template for creating your own renderer doxdox-renderer-template.

Optional Renderers

The following renderers are not bundled with doxdox and must be installed separately.

| Name | Description | Version | | ---------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | doxdox-renderer-dash | Dash renderer for doxdox. | [![NPM version](https://img.shields.io/npm/v/doxdox-rend