为非公开 Composer 包写文档的核心是“文档即代码”：版本对齐、可测试、可部署、与源码共存；文档置于包根目录 docs/ 下，通过 CI 自动构建发布，并与代码版本严格一致。
为非公开 Composer 包写文档，核心是把文档当成代码来维护：版本对齐、可测试、可部署、与源码共存。不依赖外部平台，也不手动上传 PDF 或 HTML。
文档即代码：放在包仓库里，和 src 同级
在包的根目录下建 docs/ 目录，结构清晰即可：
- docs/index.md —— 主页，简述用途、安装、快速上手
- docs/guide/ —— 指南类 Markdown（如“配置说明”“事件钩子”）
- docs/api/ —— 可选，用 phpdocumentor 生成的 API 文档（静态 HTML，提交或 CI 生成）
- docs/.vuepress/ 或 docs/docusaurus/ —— 如果需要美化，用轻量静态站工具，但配置也进 Git
用 CI 自动构建和发布文档
私有包通常托管在 GitLab、GitHub Enterprise 或自建 Git 服务器。利用其 CI 能力自动处理文档：
- 推送 main 或打 tag 时，CI 运行
npm run build:docs（或vuepress build docs） - 生成的静态文件（如
docs/.vuepress/dist）推送到同一仓库的 gh-pages 分支，或私有 Web 服务器指定目录 - 用 SSH 或内部 webhook 部署到内网文档站点（例如
docs.internal.company/pkg-name）
让文档和代码版本严格一致
用户看到的文档必须对应他正在用的包版本。关键做法：
- 文档中所有命令、配置、类名，都基于当前分支/Tag 的代码快照
- 静态站工具启用版本切换（如 VuePress 的
@vuepress/plugin-docsearch+ 版本插件），配合 Git tag 自动生成版本列表 - 在 README.md 顶部加一行：
? 对应文档：<a href="https://www.php.cn/link/1cdae395239224d198f9d07266615439">v2.4</a>，链接指向当前稳定版
本地预览 + 提交前校验
开发者写完文档要能立刻验证效果，避免“CI 失败才改”：
- 在 composer.json 的
scripts中加："docs:dev": "vuepress dev docs" - 用 markdownlint 或 remark-lint 检查格式，CI 中作为必过步骤
- 用 mdx-deck 或简单脚本验证所有代码块能否真实执行（比如截取 PHP 示例，放进临时文件
php -l检语法）
基本上就这些。不复杂但容易忽略的是：文档不是“写完就扔”，而是随每次 git push 自动同步、可回溯、可审查——它就是包的一部分。
