@ clidoc/ 核心
OpenCLI类型,离线验证,以及用于CLI Docs的Markdown渲染.
- 离线使用 Schema 包
- JSON和YAML 解析
- 📝 Markdown和页面生成
- QQ 合并作者元数据
- 完成脚本生成
从一个便携式文件分析、验证和提供CLI文件 OpenCLI 1.0.0-α.14 (英语) 文档。 这是每个 Clidoc 软件包下面的库: 如果您已经有一个 OpenCLI 文档, 直接使用, 或者用一个框架软件包配对, 从您的 CLI 生成一个 .
读取 Docs 以学习更多。 。 。 .
开始
npm install @clidoc/core
import { parse, validate, renderMarkdown, generatePages } from '@clidoc/core';
const document = parse(sourceText); // JSON or YAML; throws on invalid input
const result = validate(document); // { valid, errors }
const markdown = renderMarkdown(document);
const pages = generatePages(document, { basePath: '/cli' });
公布的软件包将精确的图案捆绑在一起 upstream/opencli/spec.schema.json,所以验证工作离线.
合适的话
| 你想这样 | 使用 |
|---|---|
| 从您的 CLI 生成文档 | @clidoc/yargs, (中文(简体) ), @clidoc/commander 或者说 @clidoc/oclif |
| 从外壳中校验、渲染Markdown、完成或MCP工具 | @clidoc/cli |
| 在文档网站上发布参考页面 | @clidoc/docusaurus 或者说 @clidoc/vitepress |
为什么Clidoc
- 与手写参考页相比: 文档来自您运行的 CLI 相同的命令定义, 因此选项和参数不能从
--help。手写指南仍然与生成的页并列. - 比较
--help仅输出 : 您可以得到一个经过验证的结构化文档(JSON/YAML),该文档也向Markdown、 shell 补全和MCP工具定义,而不仅仅是终端文本. - 比较
oclif readme数字 : 命令目标为 oclif 工程,并写入 README 。 clidoc的OpenCLI文档是框架中立的,因此yargs,command and oclif CLIs共享了一条管道和一套docs-site集成.
generatePages 返回登陆页和每个可见命令一页。 每个命令页面都包含一个生成的用法概要:需要的值使用 <value>,使用可选元素 [element],并使用可重复元素 .... 概要包括可见的指挥旗帜和继承的全球旗帜. 每页都有 id, (中文(简体) ), title, (中文(简体) ), path马克下 content命令名称 <binary> foo-bar 保留可读性 /commands/foo-bar 当它的后缀是小写 ASCII 字母,数字,以及单个连字符(最多64个字符)时,则路由。 其他名称使用规范化可读前缀(最多64个字符),保留 ~,以及全命令名称的SHA-256摘要。 每个路由只取决于其命令名,所以添加无关的命令不会改变已存在的URL. 生成器在返回任何页前拒绝消化器相撞。 这取代了以前的相撞依赖的散列后缀,因此可读形式之外名称的URL可能会被更改. 登陆链接使用生成的基础路径 。 捆绑的JSON Schema也可以在 @clidoc/core/schema。 。 。 .
validate 对照销售商JSON Schema核对文件,一旦通过,则对照上游运输的逻辑规则 validate/validate.go:立场论点不得将必要的论点置于可选论点之后, minItems编号 :maxItems 只在 variadic 参数和旗帜上有效(使用 minItems <= maxItems, (中文(简体) ), $FILE 替代源必须有一个匹配文件在 global.config,旗名和别名必须每个命令都独有,且组命令不能声明 args 或者说 flags。错误使用相同的 instancePath message 形状为图谋错误.
添加作者提供的元数据
框架软件包从您的 CLI 参数解析器中生成一个文档, 因此, 比如
examples, (中文(简体) ), exitCodes, (中文(简体) ), info.license编号 :contact, (中文(简体) ), install,以及 global 配置通常为
失踪。 加入它们 mergeDocument,然后重新验证:
import { mergeDocument } from '@clidoc/core';
const documented = mergeDocument(document, {
info: { license: { name: 'MIT', spdxId: 'MIT' } },
install: [{ name: 'npm', command: 'npm i -g my-cli' }],
commands: {
'my-cli greet': {
examples: [{ title: 'Basic', content: 'my-cli greet Ada' }],
exitCodes: [{ code: 1, status: 'BAD_USER_INPUT_ERROR', summary: 'Missing name' }],
flags: [{ name: 'language', alternativeSources: [{ type: '$ENV', property: 'LANG' }] }],
},
},
});
平面对象( E)info, (中文(简体) ), global,每个命令)递归合并. 阵列取代基数组,
除外 examples 财务报告和审定财务报表 exitCodes,该附件,以及 flags编号 :args合并的项目
对应 name - 这样你就可以添加 alternativeSources 或一个 summary 到一个生成的旗帜
不再重复其余内容。 在生成的文档中未显示的图标作为-is添加.
mergeDocument 丢出一个 Error 如果合并结果失败, 则列出每个问题
审定.
贝壳完成生成
generateCompletion(document, { shell: 'bash' | 'zsh' | 'fish', binary?: string })
验证 OpenCLI 文档,并返回独立的完成脚本。 这个
支持嵌入命令、别名、全局/本地旗帜、选项和位置
选项和隐藏条目,不依赖节点或目标CLI.
可选 binary 只覆盖已注册的可执行名称。 见
完成指南 用于激活,
支持语法和限制.
捐款
见 贡献指南。 。 。 .
许可证
麻省理工学院