php - 在 Git Workflow 中生成 API 文档

Question

不确定是否应该在此处或 Programmers 上.

生成 API 文档

我想要一些关于如何为内部项目生成 API 文档的建议。我对 Git 比较陌生，我们正在尝试实现一些合理的构建/部署实践。

我们讨论的其中一件事是确保我们的代码库有良好的文档记录，并使用诸如 PhpDocumentor2 之类的工具或许多类似工具之一生成文档。

我们已经开始实现类似于详细的 here 的工作流程。 .

---

我应该在构建文档时自动化吗？

例如，标记发布时 git 中的 pre 或 post 提交钩子(Hook)。还是应该在我将开发 merge 到发布分支时手动创建文档并提交到存储库？

为每个版本生成文档是标准做法吗？

我可能误解了这个过程，新的文档版本是否应该与 git 版本/标签相关联？

您将生成的文档存储在哪里？

在同一个存储库中？不同的存储库？托管在 Read The Docs 之类的地方还是只是在内部？ 我们目前正在进行的项目很小，但如果成功，我们希望将来将该流程推广到其他更大的项目。

上下文

该项目是一个 Magento 扩展，我们希望提供 API 文档、单元测试和符合 PSR 的代码。我缺乏有关整个工作流程如何集成的信息。 PHPunit 和 PHPDocumentor2 通过 Composer 安装在本地。

我听说过 Travis Ci，也看过 Travis Ci，但我不确定 Docs 是否属于该类别。

这个问题可能看起来很琐碎和/或微不足道，但是，我在集成和 git 工作流程方面没有太多经验，也找不到太多信息。

Answer 1

生成的文档一般有:

• 始终与代码源同步(因此“新的文档版本是否应该与 git 版本/标签相关”的问题变得毫无意义)
• 不存储在版本控制引用中(如 git 存储库)，而是随意(重新)生成(在您喜欢的任何位置)。

如果您查看具有大量代码源和大量代码文档的项目，您可以以 language Go 为例。和 his repository (一个反复无常的 repo ，但你有 mirror on GitHub as well)

• 静态文档，如 the specs, articles, release notes, ...保存在 repo 中，因为它们不是生成的，而是手动更新的，并且与源紧密相连。
• Code documentation单独保存在静态网站中。
• all go 项目的文档保存在 static website GoDoc 中, which will fetch the sources of Go projects ，并从中生成文档。