在Git Workflow中生成API文档

Question

不确定这应该在此处还是在Programmers上。

生成API文档

我想就如何为内部项目生成API文档提出一些建议。我对Git相对较新，我们正在尝试实施一些合理的构建/部署实践。

我们讨论的一件事是确保我们的代码库有充分的文档记录，并使用像PhpDocumentor2或许多类似工具之一生成文档。

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

---

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

例如，在标记版本时git中的pre或post提交挂钩。或者，当我合并开发到发布分支时，只需手动创建文档并提交到存储库吗？

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

如果新的doc发布与git发布/标记相关，我可能误解了这个过程？

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

在同一个存储库中？不同的存储库？托管在Read The Docs或内部？ 我们正在开展的当前项目规模很小，但如果成功，我们希望将来将该流程推广到其他大型项目。

上下文

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

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

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

Answer 1

生成的文档通常是：

• 始终与代码源同步（因此“如果新的doc发布与git发布/标记相关”的问题变得毫无意义）
• 没有存储在版本控制参考中（如git repo），而是（重新）随意生成（在您喜欢的任何位置）。

如果您查看具有大量代码源的项目以及广泛的代码文档，您可以举例language Go和his repository（一个mercurial repo，但您有{{3 }}）

• 像mirror on GitHub as well这样的静态文档是repo中的kepts，因为它们不是生成的，而是手动更新的，并且与源代码紧密相关。
• the specs, articles, release notes, ...分别保存在静态网站中。
• 所有 go项目的文档保存在Code documentation，static website GoDoc中，并从中生成文档。