@clidoc/亚尔格
从 Yargs 命令定义中生成 CLI 参考文件 .
- 来自您的命令的文档
- *
- QQ 构建器支持
- 只有元数据, 没有处理器运行
- 通过 opencli 发现机器
停止手写 CLI 参考文件 。 从你那里产生 驴子 命令定义,所以它们不会从 --help。 。 。 .
@clidoc/yargs 将命令转换为 打开CLI 文档,您可以验证、渲染给Markdown,并发布到 Docusaurus 或 VitePress.
读取 Docs 以学习更多。 。 。 .
开始
npm install @clidoc/yargs @clidoc/core yargs
为什么/与替代品相比
- 手写参考页 随着旗帜的改变而漂移; 这里读取您已运行的 CLI 定义 .
--help仅限 是每次一个命令的终端文本。 OpenCLI 文档结构化并经过验证,并可以使 Markdown 完全引用, shell 完成和 MCP 工具定义.- 它只读取元数据:没有处理器运行,所以生成docs没有副作用. 并非元数据(海关验证,强制,中间软件)的鼠标行为没有记录;参见"限制".
相关软件包
@clidoc/core: 验证、解析和渲染文档,加mergeDocument。 。 。 .@clidoc/cli数字 :clidoc validate, (中文(简体) ),markdown, (中文(简体) ),completion财务报告和审定财务报表mcp命令.- 以
@clidoc/docusaurus或者说@clidoc/vitepress。 。 。 . - 其他国家行动倡议框架:
@clidoc/commander, (中文(简体) ),@clidoc/oclif。 。 。 . - 文档 财务报告和审定财务报表 演示。 。 。 .
添加 docgen 给您的 CLI
createDocgenCommand 建立一个随时可以注册的 docgen 命令模块 : -o编号 :--output <file> (默认退出)和 --format <json|yaml|markdown> (默认) json) (中文(简体) ). infoFromPackageJson 文档的标题、 二进制名称和版本来源于您的 package.json。 。 。 .
import { readFileSync } from 'node:fs';
import yargs from 'yargs';
import { hideBin } from 'yargs/helpers';
import { createDocgenCommand, fromYargs } from '@clidoc/yargs';
import { infoFromPackageJson } from '@clidoc/core';
const greet = {
command: 'greet <name>',
describe: 'Print a greeting',
builder: (y) =>
y
.positional('name', { type: 'string', describe: 'Who to greet' })
.option('loud', { type: 'boolean', describe: 'Shout the greeting' }),
handler: (argv) => console.log(argv.loud ? `HELLO, ${argv.name}!` : `Hello, ${argv.name}.`),
};
const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
const info = infoFromPackageJson(pkg);
const parser = yargs(hideBin(process.argv)).command(greet);
let document;
parser.command(createDocgenCommand(() => document)).demandCommand();
// generate the document once every command, including docgen, is registered
document = fromYargs(parser, info);
parser.parse();
运行 mycli docgen --output cli.json jSON(默认),或 mycli docgen --format markdown --output reference.md 直接使 Markdown 化; 省略 --output 打印到 stdout。 安装验证器 npm install -g @clidoc/cli 运行 clidoc validate cli.json见 Yargs 演示 对于一个可运行的例子.
可选 : __opencli 用于机器发现
对于机器的发现, 匹配 上游 OpenCLI 的 Go 库中,检查隐藏的参数 __opencli yargs 前面的子命令解析参数而不是调用 .parse() 直接 : handleOpenCliRequest 打印一个 JSON 文档到 stdout( 或将其写入上游文件) -o编号 :--out <file> 命令处理器从不运行.
import { handleOpenCliRequest } from '@clidoc/core';
if (!(await handleOpenCliRequest(hideBin(process.argv), () => document))) {
parser.parse();
}
消费者可以跑步 mycli __opencli > mycli.opencli.json 或者说 mycli __opencli --out mycli.opencli.json 为发现.
限制
.check()财务报告和审定财务报表.middleware()从未援引过召回.- 构建器回调运行以收集元数据,因此使用可信赖的模块.
fromYargs拒绝同步构建器; 使用fromYargsAsync这些. - 自定义解析、强迫、验证和中间软件行为.
- 不支持的构建者方法报告其名称并给出建议
.option()或扩展fromYargs。 。 。 . - 需要的数组选项( E)
demandOption: true发射variadic: true, required: true。 。 。 . - 数组类型选项
default既不能表示 —— OpenCLI 旗下默认是单个字符串,数字,也不能表示布尔——所以fromYargs扔出一个诊断性选项,而不是释放无效文档。 在您的处理器中应用默认值( 例如) .argv.rules ?? ['basic']) (中文(简体) ).
同步构建器
fromYargs 同步运行构建器 。 如果一个建筑师 async,例如,一个懒惰地导入其子命令作为 雅格文件命令 对,使用 fromYargsAsync。它需要相同的参数,等待每个构建者,并包括一个 await。 。 。 . createDocgenCommand 接受一个同步 getDocument,因此文档只有在 docgen 运行和正常启动保持懒惰 :
import { createDocgenCommand, fromYargsAsync } from '@clidoc/yargs';
import { fileCommands } from 'yargs-file-commands';
const commands = await fileCommands({ commandDirs });
const docgen = createDocgenCommand(() => fromYargsAsync([...commands, docgen], info));
await yargs(hideBin(process.argv)).command(commands).command(docgen).parseAsync();
在此传递命令模块而不是解析器: Yargs 在操作器运行时不会暴露其已注册的命令.
高级: 通过一个明确的命令模块阵列
fromYargs 接受代替活实例的一系列命令模块,供想要从从未在解析器上注册的模块构建文档的呼叫者使用,在不同的时间运行转换,或者跳过 package.json 完全为:
import { fromYargs } from '@clidoc/yargs';
const document = fromYargs([greet], { title: 'My CLI', binary: 'mycli', version: '1.0.0' });
fromYargs 将 Yargs 命令元数据转换为 OpenCLI 1.0.0-alpha.14 文档中,从一个活实例中,或从同一模块的显式数组中,记录您的命令,加上CLI标题、可执行名称和版本. fromYargs 只读元数据;它不分析参数或运行处理器.
添加示例和退出代码
fromYargs 只知道Yargs指挥元数据暴露了什么 所以 examples, (中文(简体) ), exitCodes,以及
元数据类 info.license 从未出现在生成的文档中。 加入它们 @clidoc/core是因为
mergeDocument,替换平原 fromYargs(parser, info) 以上调用:
import { mergeDocument } from '@clidoc/core';
document = mergeDocument(fromYargs(parser, info), {
info: { license: { name: 'MIT', spdxId: 'MIT' } },
commands: {
'mycli greet': {
examples: [{ title: 'Basic', content: 'mycli greet Ada' }],
exitCodes: [{ code: 1, status: 'BAD_USER_INPUT_ERROR', summary: 'Missing name' }],
},
},
});
使用全部生成的命令密钥( E)mycli greet)将元数据添加到现有的命令中.
见 @clidoc/core 读取 为合并规则.
捐款
见 贡献指南。 。 。 .
许可证
麻省理工学院