.NET项目的独立文档 - doxygen？

Question

任务

我们希望使用以下标准维护.NET项目的一些开发人员文档：

• “文档”，最好用Markdown编写，用于提供与一段代码没有密切关系的信息（如概述，FAQ）。
• 代码和API文档的标准内联注释。因此，我们以类/接口的标准内联（XML）注释的形式（主要用于IntelliSense支持，其次是能够生成API引用），并希望继续这样做。
• 文件包含在文件中;例如如果它是一个解决方案的概述然后在解决方案中，如果它是一个项目然后在项目的文件中，版本控制的方式与代码相同（这是因为文档接近他们记录的内容，因此它们不太容易发生为了过时，这也是文档总是“在手边”）。
• 能够（从CI服务器）自动生成整个项目的可读，编译文档，包括“文档”和API的内联注释。

示例

我们的项目是第三方系统中可用的组件。对于这个项目，我们有以下类型的文档：

• 概述（项目的作用，目标是什么）
• 安装说明
• API文档
• 版本历史

我们希望让我们的开发人员和其他开发人员能够   - 从项目的源包中读取此文档   - 来自网站。

我们已经考虑过的解决方案

• 使用wiki（我们尝试Confluence）：这对于“文档”类型的文档（如概述或安装说明）很有用，但它独立于项目本身。这是另一个需要维护的系统，因为在进行开发时它不会超出一个人的眼睛，它很快就会过时。另外，还有一项任务是以某种方式将自动生成的API文档集成到其中。
• 使用Markdown文件并将其存储在代码中：这很简单，文档随时可用，并且接近文档;但是我们需要从这些文件和源文件的内联文档中生成可发布的Web包。

到目前为止，doxygen似乎是能够提供所有这些功能的解决方案。你同意吗？

请参阅“How to include custom files in doxygen”。

Answer 1

从广义上讲，这正是我目前所做的，而且我正在使用Doxygen。

然而，我担心我对.NET一无所知。我正在开发的项目是一个Java包，但包括从源代码中提取的API文档，用户指南，发布记录以及弃用等内容。

我们的范围和您的唯一内容是安装指南，但这只是因为开发人员只能在安装后阅读它。

我们让Jenkins CI在每次更改时都会构建文档。

“描述性”文本全部用Markdown编写，Doxygen处理得相当好。

下行：如果您熟悉Doxygen处理源代码文本分组的方式，您可能会感到困惑的是这些命令不能用于对Markdown中的文本块进行分组。还有一些其他特殊的奇怪之处，但如果您扫描我自己关于主题的问题（here，here和here），您可能会找到其中的大部分内容。

上升 :(我们发现有用的东西，你没有提到过）

1. 我们还可以解析Java API中的'doxygen'标记，以创建IDE（例如Eclipse）可以使用的javadoc。这意味着我们必须将自己限制在API文档中的javadoc-style命令，但这不是一个很大的限制。

2. 我们已经在doxygen'构建开关'中包含了您的开发人员手册，其中介绍了如何为手册编写文档（好的，这有点递归！）。这提供了要使用的推荐命令子集，以及是否（根据品味）您希望人们使用doxygen @subsection或Markdown ##作为标题等。

希望有所帮助。

我建议你试一试;试验你需要的每种类型的文档部分的样本，看它是否会完成你需要的整套功能。没有什么比这更烦人的记录90％，然后发现它不会做最后10％。