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

发布时间：2020-12-13 16:25:29 所属栏目：PHP教程来源：网络整理

导读：不知道这应该在这里还是在 Programmers. 生成API文档我想要一些关于如何为内部项目生成API文档的建议.我对Git来说比较新,我们正在努力实施一些完善的构建/部署实践. 我们讨论的其中一件事情是确保我们的代码库有很好的记录,并使用诸如PhpDocumentor2或许多

不知道这应该在这里还是在 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,并从中生成文档.

（编辑：李大同）

【声明】本站内容均来自网络，其相关言论仅代表作者个人观点，不代表本站立场。若无意侵犯到您的权利，请及时与联系站长删除相关内容!