10

不确定这应该在这里还是在Programmers上。

生成 API 文档

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

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

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

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

例如，标记发布时 git 中的 pre 或 post 提交钩子。或者当我将开发合并到发布分支时，是否应该手动创建文档并提交到存储库？

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

我可能误解了这个过程，新的文档版本应该与 git 版本/标签相关吗？

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

在同一个存储库中？不同的存储库？托管在Read The Docs 之类的地方还是仅在内部托管？我们目前正在进行的项目很小，但如果成功，我们希望将来将该流程推广到其他更大的项目。

语境

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

我听过并看过 Travis Ci，但我不确定 Docs 是否属于该类别。

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

4

1 回答 1

2

生成的文档一般有：

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

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

于 2013-10-24T08:06:54.887 回答