jsdoc-to-markdown
Version:
Generates markdown API documentation from jsdoc annotated source code
249 lines (244 loc) • 7.84 kB
JavaScript
/* generation options */
const jsdocDefinitions = [
{
name: 'files',
alias: 'f',
type: String,
multiple: true,
defaultOption: true,
description: 'A list of jsdoc explain files (or glob expressions) to parse for documentation. Either this or {bold --source} must be supplied.',
typeLabel: '{underline file} ...'
},
{
name: 'source',
type: String,
description: 'A string containing source code to parse for documentation. Either this or {bold --files} must be supplied.'
},
{
name: 'configure',
alias: 'c',
type: String,
typeLabel: '{underline file}',
description: 'Path to a jsdoc configuration file, passed directly to `jsdoc -c`.'
},
{
name: 'namepaths',
type: Boolean,
description: 'Print namepaths.'
}
]
const jsdoc2mdDefinitions = [
{
name: 'help',
description: 'Print usage information',
alias: 'h',
type: Boolean
},
{
name: 'config',
description: 'Print all options supplied (from command line, `.jsdoc2md.json` or `package.json` under the `jsdoc2md` property) and exit. Useful for checking the tool is receiving the correct config.',
type: Boolean
},
{
name: 'json',
type: Boolean,
description: 'Prints the data (jsdoc-parse output) supplied to the template (dmd).'
},
{
name: 'jsdoc',
type: Boolean,
description: 'Prints the raw jsdoc data.'
},
{ name: 'version', type: Boolean },
{
name: 'no-cache',
type: Boolean,
description: 'By default, repeat invocations against the same input with the same options returns from cache. This option disables that. '
},
{
name: 'clear',
type: Boolean,
description: 'Clears the cache.'
}
]
const dmdDefinitions = [
{
name: 'template',
alias: 't',
type: String,
typeLabel: '<file>',
description: 'A custom handlebars template file to insert documentation into. The default template is `\\{\\{>main\\}\\}`.'
},
{
name: 'private',
type: Boolean,
description: 'Include identifiers marked {bold @private} in the output'
},
{
name: 'heading-depth',
type: Number,
alias: 'd',
description: 'Root markdown heading depth, defaults to 2 ({bold ##}).'
},
{
name: 'plugin',
type: String,
typeLabel: '{underline module} ...',
multiple: true,
description: 'Use an installed package containing helper and/or partial overrides.'
},
{
name: 'helper',
type: String,
typeLabel: '{underline module} ...',
multiple: true,
description: 'Handlebars helper modules to override or extend the default set.'
},
{
name: 'partial',
type: String,
typeLabel: '{underline file} ...',
multiple: true,
description: 'Handlebars partial files to override or extend the default set.'
},
{
name: 'example-lang',
type: String,
alias: 'l',
description: 'Specifies the default language used in {bold @example} blocks (for syntax-highlighting purposes). In the default gfm mode, each {bold @example} is wrapped in a fenced-code block. Example usage: {bold --example-lang js}. Use the special value {bold none} for no specific language. While using this option, you can override the supplied language for any {bold @example} by specifying the {bold @lang} subtag, e.g {bold @example @lang hbs}. Specifying {bold @example @lang off} will disable code blocks for that example.'
},
{ name: 'name-format', type: Boolean, description: 'Format identifier names as code (i.e. wrap function/property/class etc names in backticks).' },
{
name: 'no-gfm',
type: Boolean,
description: 'By default, dmd generates github-flavoured markdown. Not all markdown parsers render gfm correctly. If your generated docs look incorrect on sites other than Github (e.g. npmjs.org) try enabling this option to disable Github-specific syntax. '
},
{
name: 'separators',
type: Boolean,
description: 'Put {bold <hr>} breaks between identifiers. Improves readability on bulky docs. '
},
{
name: 'module-index-format',
type: String,
alias: 'm',
description: 'When muliple modules are found in the input source code, an index is generated. It can be styled by one of the following options: {bold none}, {bold grouped}, {bold table} or {bold dl}.'
},
{
name: 'global-index-format',
type: String,
alias: 'g',
description: 'When muliple global-scope identifiers are found in the input source code, an index is generated. It can be styled by one of the following options: {bold none}, {bold grouped}, {bold table} or {bold dl}.'
},
{
name: 'param-list-format',
type: String,
alias: 'p',
description: 'Two options to render {bold @param} lists: {bold list} or {bold table} (default). Table format works well in most cases but switch to {bold list} if things begin to look crowded. '
},
{
name: 'property-list-format',
type: String,
alias: 'r',
description: 'Two options to render {bold @property} lists: {bold list} or {bold table} (default).'
},
{
name: 'member-index-format',
type: String,
description: 'Two options to render member lists: {bold list} or {bold grouped} (default). The {bold list} view is loosely-based on the nodejs docs.'
},
{
name: 'clever-links',
type: Boolean,
description: 'By default, all {bold \\{@link\\}} tags are rendered in plain text. If `--clever-links` is set, URL \\{@link\\} tags are rendered in plain text, otherwise monospace.'
},
{
name: 'monospace-links',
type: Boolean,
description: 'By default, all {bold \\{@link\\}} tags are rendered in plain text. If `--monospace-links` is set, all links are rendered in monospace format. This setting is ignored if {bold `--clever-links`} is set.'
},
{
name: 'EOL',
type: String,
description: 'Specify ether `posix` or `win32`. Forces all line endings in the dmd output to use the specified EOL character.'
}
]
/* mix in the jsdoc-parse and dmd options */
const definitions = jsdocDefinitions
.map(def => {
def.group = 'jsdoc'
return def
})
.concat(jsdoc2mdDefinitions.map(def => {
def.group = 'jsdoc2md'
return def
}))
.concat(dmdDefinitions.map(function (def) {
def.group = 'dmd'
return def
}))
export default {
definitions: definitions,
usageSections: [
{
header: 'jsdoc-to-markdown',
content: 'Generates markdown documentation from jsdoc-annotated source code.'
},
{
header: 'Synopsis',
content: [
{
cmmd: '$ jsdoc2md <jsdoc-options> [<dmd-options>]'
},
{
cmmd: '$ jsdoc2md <jsdoc-options> {bold --jsdoc}'
},
{
cmmd: '$ jsdoc2md <jsdoc-options> {bold --json}'
},
{
cmmd: '$ jsdoc2md <jsdoc-options> {bold --namepaths}'
},
{
cmmd: '$ jsdoc2md {bold --help}'
},
{
cmmd: '$ jsdoc2md {bold --config}'
}
]
},
{
header: 'General options',
content: 'Main options affecting mode. If none of the following are supplied, the tool will generate markdown docs.'
},
{
optionList: jsdoc2mdDefinitions
},
{
header: 'jsdoc options',
content: 'Options regarding the input source code, passed directly to jsdoc.'
},
{
optionList: jsdocDefinitions,
},
{
header: 'dmd',
content: 'These options affect how the markdown output looks.'
},
{
optionList: definitions,
group: 'dmd',
tableOptions: {
maxWidth: Math.min(process.stdout.columns, 100)
}
},
{
content: [
{
col1: 'Project repository:',
col2: '{underline https://github.com/jsdoc2md/jsdoc-to-markdown}'
}
]
}
]
}