2

我试图找到一个软件来帮助一个小型（约 3-5 人）团队编写 A）用户指南和 B）软件可扩展部分的 API 参考。我们非常喜欢使用某种形式的 wiki 的想法，但有一些具体要求：

  • 将手册导出为在线和离线可读形式的能力（例如，可以放在网络服务器上或在本地读取的一堆 HTML 文件）

  • 从 XML 文档自动创建页面。我们使用 VB.Net/C#.Net 编写，大多数 API 特定的东西已经有 XML 文档注释。如果手册的 API 部分可以指定类、方法、参数等，而且还允许作者从其他人链接到这些页面，那就太好了。（例如，有一个详细说明foo类的页面，并且能够有一个详细说明如何使用 API 链接到该foo.increaseBarCount()方法页面的一般任务的页面）。

仅此而已，除了显而易见的（'易于使用'，'为我完成所有写作，以便我可以摆脱编写技术文档的乏味'，'不会引发全球热核战争'）。

有这样的软件吗？可以使用 mediawiki 扩展拼凑类似的系统吗？

4

2 回答 2

1

至于“从 XML 文档自动创建页面”，显而易见的解决方案是doxygen。它从源代码中嵌入的特殊文档注释创建文档（HTML、PDF、WinHelp ...）。它处理 Javadoc 注释、Qt 样式注释和 XML 注释。如果您生成 HTML，则页面名称是可预测的，因此很容易链接到；doxygen 还可以自动创建内部链接。如果您使用其他格式，您可能可以嵌入某种锚来引用页面名称，但我不太确定。

关于一般文档，我们在使用 wiki 方面有很好的经验。我们使用MediaWiki（以 Wikipedia 闻名），但任何体面的 wiki 都可能会这样做。我们从未尝试过打印它，但 Google 展示了来自 MediaWiki 的各种打印解决方案，因此您可以轻松完成某些工作。

我们喜欢将 wiki 用于文档的主要好处是，当您发现错误时，您可以轻松地更改它们；让他们保持新鲜。此外，不用担心副本过时。

于 2011-03-01T08:55:04.087 回答
0

您可以查看 Atlassian Confluence。我相信他们为小型团队提供免费版本（可能只是一个报价，所以从长远来看，你可能最终会付费，不知道）。他们也有一个 API，所以如果什么都不存在的话，编写一个实用程序来提取 XML C# 文档并使用 API 从它创建页面并不难。wiki 易于使用，并且被开源项目大量使用。例如，您可以查看ANTLR 文档，即 Confluence。

于 2011-03-01T08:47:32.627 回答