如何为一个非公开的Composer包编写和托管文档？（文档即代码）

为非公开 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）

让文档和代码版本严格一致

用户看到的文档必须对应他正在用的包版本。关键做法：

标签： php vue html js markdown git json composer github npm 工具 ai