如何管理开源项目的文档？[关闭]

我是一个成长中的开源项目的创建者。目前，我正试图找出管理文档的最佳方法而感到沮丧。这是我考虑过的选项：

• HTML网站
• Github Wiki
• Github上托管的Markdown文件
• 将所有文档放在Github中README.md

该文档已经用Markdown编写，我只是想不出如何使它可用。我真的很喜欢Git，因为我可以分支和标记文档，就像可以分支和标记源代码一样。

我可以使用Markdown库将Markdown转换为HTML并将其显示在样式化的网站上。每当发生更改时，我都需要将更改上传到网站，并且很难管理文档的所有不同“标签”。

Github Wiki（据我所知）不会根据您所在的分支进行更改。因此，在任何给定时间，我只能以Github Wiki形式获得文档的“主”版本。

将所有内容放到Github自述文件中非常简洁。我可以进行分支和标记，但是使用起来有点累，而且不便于导航。

我是否缺少一些很棒的解决方案？我还有什么其他选择？

我要说的一件事是，文档必须位于源代码文件中（使用所需的任何标记），然后由这些文件自动生成文档。
至少在您的站点上，您可以将文档的格式化下载作为源软件包的一部分生成，因此用户不需要特定的doc工具

其他人修复/添加功能，然后编辑/添加紧邻同一文件的一些标记文档的机会可能很小，但是他们在另一文档存储库中找到完全不同的文件来执行相同操作的机会很小小于零。

您始终可以拥有一个tutorial.h，如果需要，它可以包含大量文本-但请将其视为源代码的一部分

如果您的项目是一个库，那么没有什么比Javadoc风格的文档更能从代码本身的注释中记录API语法了。

至于教程，用法示例等方面的文档。我强烈建议使用Wiki格式。我见过的其他项目在不同的分支都有单独的页面。当您开始一个新分支时，您只需将尚未更改的内容复制到新页面并从那里进行更新。

我推荐维基的原因是轶事，但来自个人经验。我曾多次在开放源代码项目中提供过文档更新，但是这些更新都出现在Wiki上。如果我想弄清楚某些内容，而文档却具有误导性或无益，在我弄清楚之后，我将在我使用文档的同时更新Wiki，使我记忆犹新。如果不是出于回馈的感觉，至少是因为我知道我很可能需要在一两年内重新查找一下。

如果没有Wiki，那么在弄清楚文档的生成方式，存储位置，从源代码管理获取最新信息，如何进行编辑，进行实际编辑以及浏览邮件列表以接受补丁。

如果您希望对文档进行严格控制，请务必使用最适合您的文档，因为您将是唯一对其进行更新的人。如果要鼓励社区参与，请使用Wiki。

源代码托管的Markdown文件效果很好。

例如，基于RST的docutils工具可以从一组文档中创建HTML或LaTex（和PDF）。

实际上，这结合了选项1和选项3。

如果您不介意将文档从Markdown转换为reStructuredText，请考虑Sphinx 。它与markdown一样简单，但功能强大得多。