Doxdox Save

⚠️ 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 [email protected] -g

Locally

$ npm install [email protected] --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 [email protected] --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.
doxdox-renderer-github-wiki	GitHub Wiki renderer for doxdox.
doxdox-renderer-pdf	PDF renderer for doxdox.

Questions

If you have any questions regarding the use of doxdox, please use either GitHub Discussions 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