doxdown
v2.0.1
Published
jsDoc to MkDocs markdown generator
Downloads
3
Maintainers
Readme
doxdown
doxdown is a jsDoc to MkDocs markdown generator. It allows you to control your documentation on a comment by comment basis, choosing the page and document the comment belongs to. This is especially useful when you need to document an API separate to the rest of your codebase.
Running it on a directory with the default options will parse all nested JavaScript files and output a ./doxdown
folder. Inside will be a folder for each document with Markdown files and a mkdocs.yml
file in the format expected by MkDocs. You can then run MkDocs on any of those folders to build a site that you can deploy to a server.
Installation
The easiest way to get doxdown is with NPM: npm install doxdown --global
Usage / Options
Use the command doxdown
with the following options to generate your docs:
Name | Alias | Default | Description
--- | :---: | --- | ---
ignore | i | .git,node_modules
| comma-separated list of files/directories to ignore
out | o | ./doxdown
| relative path to the output directory
regex | r | \.js$
| regex string for matching files in the source directory
src | s | ./
| relative path to the source directory
Comment Format
doxdown looks for jsDoc-style comments with a special @docs
tag in the format document [// page] // section
which describes where the comment belongs in which document. Use a jsDoc @desc
to describe the function or event in the format @name - description
. You can have any number of @params
or @data
tags and one @returns
tag.
/**
* @docs Some Docs // Users & Accounts // User Helpers
* @desc getUsernames - A description of getUsernames
* @param {Object[]} users - An array of user objects
* @param {String} users[].name - A user's name
* @param {Number} limit - The max number to return
* @returns {String[]} An array of usernames
*/
function getUsernames (users, limit) {
const usernames = [];
for (let i = 0; i < limit; i++) {
usernames.push(users[i].name);
}
return usernames;
}
/**
* @docs Tracking // Registration
* @desc registration-complete - Fires when a user successfully completes registration.
* @data {String} forename - The user's forename
* @data {String} surname - The user's surname
* @data {Date} dob - The user's date of birth
* @data {Object} address - An object containing details of a user's address
* @data {String} address.house - The house name/no. of the user's address
* @data {String} address.postcode - The postcode of the user's address
*/
SomeTrackingAPI.trigger('registration-complete', {
forename: "Sherlock",
surname: "Holmes"
dob: dateOfBirth,
address: {
house: "221B",
postcode: "NW16XE"
}
});
TODO
- Replace
regex
option with glob pattern for matching files and directories.