我正在寻找一种工具来构建我的文档。Sandcastle 很好,但它似乎不适用于 .NET 核心项目,而且陈旧且有缺陷。
有没有可以为 .NET(核心)项目生成文档的好选择?
所需功能:
- 可以导出静态网站
- 与 .NET 核心的良好兼容性。
- 使用一些模板技术易于定制
- 可以自动生成相关类型/类之间的链接
- 支持 XML 注释
我正在寻找一种工具来构建我的文档。Sandcastle 很好,但它似乎不适用于 .NET 核心项目,而且陈旧且有缺陷。
有没有可以为 .NET(核心)项目生成文档的好选择?
所需功能:
经过一段时间的搜索和尝试,我找到了一个完美的替代方案。
主要特点:
DocFX 直接从 .NET 源代码生成 API 文档。您可以在源代码的 Triple-Slash-Comments 中使用 Markdown 语法。它甚至允许您使用 Markdown 文件向 API 文档添加其他主题。当然,也支持纯 Markdown 文件。您可以在一个命令中创建包含概念主题和 API 主题的静态网站。
DocFX 可以在 Linux、macOS 和 Windows 上运行。生成的网站是纯静态的,无需额外配置即可部署到 Github Pages、Azure 网站或任何 Web 主机。
DocFX 提供了一种灵活的方式来轻松自定义模板和主题。
并且它是使用 .NET core 开发的,并由.NET core docs使用。
我使用 DocFx 从代码和注释构建了我的文档。然后我将该文档作为静态网站发布在 GitHub 页面上。它体积小、易于使用和集成,但仍然功能强大。
您可能对其他人推荐的其他文档生成器感兴趣:
(介绍来自他们的官方网站,可能听起来像广告。但我没有以任何方式宣传他们。)
GhostDoc 是一个 Visual Studio 扩展,可根据方法和属性的类型、参数、名称和其他上下文信息自动生成 XML 文档注释。
VSdocman 是一款终极、快速且易于使用的 .NET 文档工具,适用于每个 Visual Studio C# 和 VB 开发人员。
文档!X 是自动化文档工具和完整创作环境的组合,可用于为 .NET、Web 服务、数据库、XSD 模式、COM 组件和类型库、Java 和 Javascript 创建、发布和维护准确、专业的质量文档.
HelpStudio 是创建和发布程序、文档和帮助系统并将它们与您的桌面、Web 或移动应用程序或组件集成的最快、最简单的方法。
Doc-O-Matic 是一个软件源代码文档和帮助创作工具。Doc-O-Matic 获取源代码和注释,添加概念性主题和外部输入,并从中生成文档。
Monodoc 是一组用于查看和编辑 Mono 类库文档的库和应用程序。
从 XML 注释和 .NET 库生成多种格式的 API 文档,快速而简单。实时查看文档。免费和开源。
Sandcastle 帮助文件生成器从v2017.5.15.0 版本开始支持 .NET Core 项目。
...
- 添加了一个新的跨平台反射数据集文件 ( CrossPlatform.reflection )。这是用于您要记录的所有 .NETCore 和 .NETStandard 程序集和项目的首选框架版本设置。此外, 使用此框架版本将允许您使用 .NETCore、.NETStandard 和 .NETFramework Visual Studio 项目或程序集的任意组合作为文档源。
...
- 修复了项目文件处理,以便它可以在使用 TargetFrameworks 属性的 .NETCore/.NETStandard 项目中定位程序集和 XML 注释文件。
...
- 对构建引擎进行了各种更新,以处理 .NETCore/.NETStandard 项目和跨平台反射数据集。
- 修改了构建引擎,以便在确定是否排除选定反射数据集中的引用程序集时比较完整的强名称。这允许在生成反射信息(即 .NETCore 和 .NETStandard 框架程序集的 NuGet 版本)时包含具有不同版本的同名程序集作为引用。
- 添加了对解析 .NET Core 和 .NET Standard 项目文件中的包引用(PackageReference 元素)的支持。生成反射信息时,包和任何依赖包中的所有程序集都会自动添加为参考程序集。
...
有两个 Sandcastle 项目,来自 Microsoft 的原始 Sandcastle 不再处于积极开发中,以及...
...积极维护。在这方面,沙堡仍然是一个选择。
另一种选择是我最近创建的一个叫做Doxie。它建立在 Aurelia 之上并使用 Bootstrap,这使得它很容易主题化。虽然它仍然有一些限制,但如果你想要一些开源且相对易于使用的东西,这可能就足够了……它也适用于 .NET Core 程序集。