豫言 / 文档网站生成器 @ 0.1.0
根据源码及类型信息生成文档网站。
包说明.汉语.md
# 文档网站生成器
根据包配置、源码及检查后的类型信息生成可离线阅读的文档网站。
## 包身份
所有者：豫言。包版本：0.1.0（本轮初始包版本，不代表编译器命令行版本）。
本包为可执行文件类型，不可被其他包依赖；包内模块仍可互相引用。类型典中的入口和文件名见包配置，程序产物为 `yy文档网站生成器`。
## 使用
在仓库根目录运行：
```sh
node 豫言操作系统/宿主/节点/宿主.cjs yy豫构.wasm 检查 文档网站生成器
node 豫言操作系统/宿主/节点/宿主.cjs yy豫构.wasm 构建 文档网站生成器
```
依赖及说明路径以 [包配置](文档网站生成器。包。豫) 为准。构建不会自动运行程序；有发布或服务副作用的工具应先阅读其入口源码。
### 按包生成与发布
在仓库根目录运行，生成器从这里读取共用界面资源并发现包：
```sh
node 豫言操作系统/宿主/节点/宿主.cjs yy文档网站生成器.wasm 构建包 库/包配置/包配置。包。豫 /tmp/发布材料/文档
# 外部包放在“外部包目录/所有者/包目录”下；最后一个参数可省略。
node 豫言操作系统/宿主/节点/宿主.cjs yy文档网站生成器.wasm 构建包 /tmp/外部包/张三/例包/例包。包。豫 /tmp/例包发布/文档 /tmp/外部包
```
输出目录必须不存在或为空。生成器使用与豫构相同的配置解析器、所有者身份、直接依赖规则和包上下文；不会下载或安装依赖，缺失依赖会报错。按包枚举全部源码，排除嵌套包、符号链接、忽略目录及 `。测试。豫`。源码按路径排序；每个模块及所需依赖通过类型检查后，只为目标包的模块生成页面，不执行包代码。首页展示所有者、包名和版本，包说明页保留双语说明原文（按纯文本显示，不渲染 Markdown）。
包管理服务与生成器通过静态文件交接，没有远程生成 RPC：
1. 本地生成 `文档/index.html`、模块页、包说明页及本地 CSS/JS。
2. 发布者将整个 `文档/` 连同 `源码/`、`构建/`、必要的 `运行/` 放入同一个 ZIP，上传到 `POST /api/releases/zip`。
3. 服务静态解析包配置、检查必要材料并展开存储，不运行编译器，也不验证文档确由本工具生成。
4. 门户通过 `docsUrl` 在独立内容域的沙箱中展示文档。页面采用相对资源链接，兼容版本 URL 前缀；Cookie 和历史记录不可用时，语言切换仍能在当前页面生效。
生成器不创建 ZIP、不上传、不调用账户接口。包名、版本和说明以源码中的包配置为准，发布前应从同一份源码重新生成。当前输出仍依赖仓库中的界面资源，并非可脱离仓库安装的独立发行包。
### 官网兼容模式与验证
`node 豫言操作系统/宿主/节点/宿主.cjs yy文档网站生成器.wasm 构建 应用/豫言编译器/入口。豫 dist/文档` 保留入口依赖闭包模式，供本地离线浏览使用。此模式会展示依赖包模块，不适合作为单包发布文档。
```sh
node 豫言操作系统/宿主/节点/宿主.cjs yy豫构.wasm 文件 应用/文档站/文档网站生成器/生成。测试。豫 --输出 yy文档生成测试.wasm
node 豫言操作系统/宿主/节点/宿主.cjs yy文档生成测试.wasm
node --test 应用/文档站/库/文档界面/界面测试.mjs
```
回归测试覆盖完整包枚举、依赖隔离、包身份、双语说明、拒绝混入旧产物以及旧入口模式；文档界面测试覆盖内容沙箱禁止存储时的双语界面。
## 维护
每个模块还输出同名 `.json`，包含 `names` 数组，每项为 `name`、`type`、`description`、`source`。本地声明的说明优先；明确的直接转导出会回查原定义注释，追踪最多 32 层，每篇源码只解析一次。`source` 仅在目标属于本次输出模块时填写 `source/包内路径`，不会泄露本机绝对路径。主站统一浏览器使用这些字段安全渲染文档，与源代码在右侧开关切换，不直接插入上传 HTML。
生成目录包含 `模块映射.json`，内容为 `{source, document}` 条目数组；`source` 是目标包内路径，`document` 是对应生成页名。包管理器据此实现按文件“文档 / 源代码”切换，不依赖模块编号猜测文件身份。入口兼容模式仍使用其原有显示路径。
修改接口时更新本说明；修改包身份、版本或构建组成时同步更新包配置。说明文件不参与模块导入。
界面资源来自 `应用/文档站/库/文档界面/`，不依赖官网目录。
文档界面测试使用 jsdom；通过 `YY_DOM_MODULE` 指定已安装的 jsdom 模块入口后运行上述 Node.js 测试。
包说明.文言.md
# 文档网站生成器 各模块另出同名 JSON，names 各录 name、type、description，供主站与源码同器陈列；右侧易文源，不纳客之 HTML。 成篇并出“模块映射.json”，各录 source 与 document，明源码与页面之属。按包者 source 为包内之径，旧入口之式仍用原显示路径。 ## 以包成文 于仓库根行 `node 豫言操作系统/宿主/节点/宿主.cjs yy文档网站生成器.wasm 构建包 库/包配置/包配置。包。豫 /tmp/发布材料/文档`。外包另授末参，为外包总目录；其内以所有者分居。所出之目录须新或空，免旧篇杂入。 此器与豫构共用解籍、辨主、寻依及包上下文之法；不代取所依。遍录本包诸篇，除别包、链接、忽略目录及 `。测试。豫`，按径定序。先验诸篇及所依之类，而后惟书本包公名。首页载主、名、版；说明页并存汉语、文言原文，以纯文陈之，不解 Markdown。 包府不召此器。发布者先于本地成 `文档/index.html`、模块诸页、说明与界面资源，再合 `源码/`、`构建/`、必要之 `运行/` 为一 ZIP，送 `POST /api/releases/zip`。包府静解其籍，验所需材料而藏之，不编不行，亦不验其文果出此器。门户取 `docsUrl`，以别域沙箱示之。诸页之径皆相对；禁 Cookie 与历史记录，仍可于当页易辞。 此器不制 ZIP，不上传，不涉账户；发布前当据同源重生成。界面资源仍取仓库，尚非离库可装之发行包。 旧命 `构建 入口文件 【输出目录】` 仍循入口及所依，供本地阅览，非单包之文。验之：先构建生成器，再行 `node 豫言操作系统/宿主/节点/宿主.cjs yy豫构.wasm 文件 应用/文档站/文档网站生成器/生成。测试。豫 --输出 yy文档生成测试.wasm`、`node 豫言操作系统/宿主/节点/宿主.cjs yy文档生成测试.wasm` 及 `node --test 应用/文档站/库/文档界面/界面测试.mjs`。所验为诸篇齐备、所依不杂、身份与双语说明、旧页不混、旧命可行及沙箱易辞。 根据源码及类型信息生成文档网站。 ## 籍与用 所有者曰豫言，版本暂定 0.1.0。此包之版本，非编译器命令所报之版本。 此包不供他包所依，包内诸书仍可相引。程序名曰 `yy文档网站生成器`，入口依包籍所载。 在仓库之根行 `node 豫言操作系统/宿主/节点/宿主.cjs yy豫构.wasm 检查 文档网站生成器` 以验其籍。行 `node 豫言操作系统/宿主/节点/宿主.cjs yy豫构.wasm 构建 文档网站生成器` 以成其器，不自行之。 所依与说明之径皆见[包籍](文档网站生成器。包。豫)。变接口则修说明，变身份与组成则修包籍。说明不作模块。 诸名之 JSON 载 `name`、`type`、`description`、`source`。本注为先，转出循实引用而寻原注，三十二层而止；一篇析注一次。来源惟列本次所出之篇，以 `source/包内路径` 记之，不泄本机绝对路径。 界面取材于 `应用/文档站/库/文档界面/`，不依官网。 界面之验用 jsdom，先以 `YY_DOM_MODULE` 指其已装入口，乃行 Node.js 之验。