主页 / 问题 / 634889
Accepted
while1pass
Asked:2020-03-03 17:22:15 +0000 UTC2020-03-03 17:22:15 +0000 UTC

在哪里存储文档和支持项目文件？

  • 772

与代码无关的文档和支持文件存放在哪里，比如README.md的截图？

根据截图，我在enSO上找到了两个答案：

但是这里更多地涉及到通过 Markdown 格式化 README.md 的问题。我对存储辅助数据的最佳实践很感兴趣。选择什么地方存放？单独的分支或存储库？如何使用这些支持数据？

到目前为止，我自己看到了以下解决方案。我在项目中创建了一个带有辅助数据的分支，并将屏幕截图放在那里，我已经从 README.md 文件访问它们。

对于文档，情况类似；我认为虽然项目很小，但码头可以存储在一个存储库中。

我目前正在使用 GitLab/GitHub。

请分享您的经验。

git

4 个回答

  1. 最好将文档（引用它的屏幕截图和图表）保存在与代码相同的分支中。例如，在项目根目录的单独目录中，即docs目录。文档与代码越“接近”，代码和文档之间出现差异的可能性就越小。

    对于许多框架和构建系统，都有存储代码文档的规则。例如，maven希望您有一个带有文档的站点目录，以便maven可以对其进行格式化并将其上传到站点。

    此外，如果没有代码文档，许多框架可能会出错。

    有各种用于构建系统的插件可以帮助您创建、检查和发布文档。例如，AsciiDoctor有适用于各种构建系统的插件。

    • 11

  2. 如果文档是由不同的人开发的一个单独的项目，并且与代码没有任何关系，那么值得启动一个单独的存储库。

    例如，github 通过在 wiki 下创建一个完全独立的存储库来做到这一点，可以单独管理并保留更改历史记录。

    • 4

  3. 一、意见

    我最喜欢的方法是为文档创建一个单独的站点。这就是开源项目的开发人员所做的，在我看来这是最严肃和最重要的。

    如果您使用静态网站生成器，这可以免费完成。

    2. 使用有助于将它们放置在各个站点上的工具制作的文档示例

    1. mkdocs -示例

    mkdocs

    1. ReadTheDocs -示例

    阅读文档

    1. Sphinx -一些使用 Sphinx 的项目；例子：

    狮身人面像

    3.争论

    主要论点是托管 HTML 站点的托管限制低于在 BitBucket、GitHub（但不是BitBucket Pages、GitHub Pages）、GitLab 和类似资源上托管文档时必须处理的限制。

    假设您决定将文档README.MD和其他.md文件放在 GitHub 上：

    3.1 可用

    1. Markdown 允许的任何内容，

      但

      不是 Markdown 中通过 HTML 实现的东西，也不是 Markdown 本身。

      简单来说，你可以使用黑白文本、图像、表格，但仅此而已。

    3.2 不可用

    1. 你将无法使用 JavaScript：你将无法使用 jQuery 插件，在 Bootstrap 上制作一个方便的菜单以方便用户浏览你的文档，你将被迫拒绝自己的小东西，比如自定义滚动条等.
    2. 如果不转到另一个页面查看视频，您将无法嵌入视频。

    4. 静态站点生成器的特点

    1. 直接用 HTML 写网站不是很方便。幸运的是，静态站点生成器的功能之一是将用您选择的标记（例如 Markdown 或reStructuredText）编写的文本直接渲染到 HTML 中。
    2. 与构建工具集成的能力：例如，我使用 Pelican + Grunt + CoffeeScript + Stylus。
    3. 有专门为编写项目文档而设计的生成器。第 2 节中给出了一些示例。此外，如果您对现有主题感到满意，则可以使用它们，而不是从头开始编写。

    5.附加链接

    • 4
  4. Best Answer

    可能最好的解决方案是使用 confluence，并将项目存储在 bitbucket (jira) 或 tfs 上，如果是 windows 开发，则有非常强大的机会来维护文档和存储辅助文件

    • 2

相关问题