mirror of
https://github.com/jsdoc2md/jsdoc-to-markdown.git
synced 2026-01-25 14:16:45 +00:00
249 lines
7.7 KiB
JavaScript
249 lines
7.7 KiB
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}'
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|