php – 在Git工作流程中生成API文档

不知道这应该在这里还是在 Programmers.

生成api文档

我想要一些关于如何为内部项目生成api文档的建议.我对Git来说比较新,我们正在努力实施一些完善的构建/部署实践.

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

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

文档建立时应该自动化吗？

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

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

我可能误解了这个过程,一个新的文档释放与git release / tag有关吗？

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

在同一个仓库？一个不同的仓库？主办的地方像Read The Docs或内部？
目前我们正在开展的项目很小,但如果成功,我们希望将来进一步推广到其他较大的项目.

上下文

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

我听说过Travis Ci,但我不知道Docs是否属于这个类别.

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

生成的文档通常是：

>始终与代码源同步(所以“应该有一个新的文档释放与git release / tag相关联”的问题变得模糊)
>不存储在版本控制引用(如git repo)中,而是(随意)生成(在任何您喜欢的位置).

如果您查看具有大量代码源的项目和广泛的代码文档,您可以以language Go和his repository为例(一个mercurial repo,但是您具有mirror on GitHub as well)

>像the specs,articles,release notes,…这样的静态文档是repo中的kepts,因为它们不是生成的,而是手动更新的,并且与源连接.
> Code documentation分开存放在静态网站中.
>所有go项目的文档保存在static website GoDoc,which will fetch the sources of Go projects,并从中生成文档.

原文地址：https://www.jb51.cc/php/132660.html