docsbydoxdox⚠️ 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 yourpackage.jsonfile.
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 yourpackage.jsonfile.
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 yourpackage.jsonfile.
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
doxdoxand 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
doxdoxand 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.