在Git Workflow中生成API文档

Question

不确定这应该在这里还是程序员.

生成API文档

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

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

我们已经开始实施类似于此处详述的工作流程.

---

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

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

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

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

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

在同一个存储库中？不同的存储库？像Read The Docs或仅在内部托管？我们正在开发的当前项目很小,但如果成功的话,我们希望将来将这个过程推广到其他更大的项目.

上下文

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

我听过并看过Travis Ci,但我不确定Docs是否属于那个类别.

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

Answer 1

生成的文档一般有：

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

如果您查看一个具有大量代码源和大量代码文档的项目，您可以以Go 语言及其存储库（一个 Mercurial 存储库，但您在 GitHub 上也有镜像）为例。

• 静态文档（如规格、文章、发行说明等）保存在存储库中，因为它们不是生成的，而是手动更新的，并且与源紧密链接。
• 代码文档单独保存在静态网站中。
• 所有Go 项目的文档都保存在静态网站GoDoc中，该网站将获取 Go 项目的源代码，并从中生成文档。