在Git工作流中生成API文档

Question

不确定这是在这里还是在程序员上。

生成API文档

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

我们讨论的问题之一是确保我们的代码库有良好的文档记录，并使用类似于PhpDocumentor2或许多类似工具之一的工具生成文档。

我们已经开始实现一个类似于一个详细的这里的工作流。

当文档生成时，我应该自动化吗？

例如，在标记发布时，git中的预提交钩子或后置提交钩子。或者，当我合并开发到一个发布分支时，应该手动创建文档并提交到存储库吗？

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

我可能误解了这个过程，一个新的文档发布应该与git发布/标记相关吗？

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

在同一个仓库里？不同的存储库？托管在像读文档这样的地方，还是内部托管？目前我们正在进行的项目规模很小，但如果成功的话，我们希望在未来的其他大型项目中推广这一过程。

上下文

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

我听说过，也看过崔维斯·奇，但我不确定医生是否属于这一类。

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

Answer 1

所生成的文件一般如下：

• 始终与代码源同步(因此，“新文档发布是否与git发布/标记相关”的问题就没有意义了)
• 不是存储在版本控制引用(如git )中，而是(重新)随意生成(在您喜欢的任何位置)。

如果您查看一个具有大型代码源和大量代码文档的项目，可以以语言围棋和他的储存库 (一种汞回购，但您有GitHub上的镜像)为例。

• 像规格，文章，发行说明，.这样的静态文档是回购中的概念，因为它们不是生成的，而是手动更新的，并且与源紧密相连。
• 代码文档单独保存在静态网站中。
• 所有go项目的文档都保存在GoDoc、，它将获取Go项目的来源。中，并从它们生成文档。