生成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,并从中生成文档.
