Skip to content

πŸ“˜ JSDoc to Markdown, Bootstrap, and custom JavaScript template documentation generator.

License

Notifications You must be signed in to change notification settings

docsbydoxdox/doxdox

Repository files navigation

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

doxdox

Tests NPM version NPM downloads per month doxdox documentation Join the chat at https://discord.gg/nNtFsfd

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. NPM version

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. NPM version

Renderers

Default Renderers

The following renderers are bundled with doxdox.

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

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
doxdox-renderer-github-wiki GitHub Wiki renderer for doxdox. NPM version
doxdox-renderer-pdf PDF renderer for doxdox. NPM version

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