最近随着 AI 高涨，时间文档因能为模子提供高质地凹凸文而重新成为热门。最近构兵的几个开源形貌在用一个叫 Lunet 的器具来生成 API 参考文档，我也就随着评估了一下这个器具我方法样上的可用性。天然它是个可以的 API 索要器，但联想者并莫得尝试去治理更深层的问题让每个使用它的形貌都我方高度定制，是以惟有作罢。

LeXtudio Inc. 整个文档网站都一经基于开源的 Sphinx 基础行动搭建况且运行了好多年。自关联词然，我又回到了一个十年前就念念考过的问题，如何把 .NET API 文档生成和 Sphinx 内容经管整合到一都。为什么咱们不可径直用现存的 .NET 文档器具呢？谜底需要回溯 .NET 文档器具这二十五年来的历史，一个对于生态分散、计策调动，以及开源 .NET 社区得我方早先治理问题的故事。

NDoc 的年代：生机与千里寂（2001-2006）

故事天然从 NDoc 运转，一个发祥于 2000 年代初的社区形貌，由 Jason Diamond、Jean-Claude Manoli、Kral Ferch 等东谈主参与艳羡，把 JavaDoc 的一套搬到了 .NET 平台。C# 编译器可以在生成法子集的同期输出 XML 文档详实，NDoc 就拿着这些输入，滚动成视觉末端专科的参考文档， 有多种演示作风， 辅助庸碌的输出文献神志（致使包含 LaTeX 这么萧索的）。对同期期兴起的开源 .NET 形貌来说，NDoc 即是阿谁必备的器具。它的联想很求实，可推广，免费开源。

当 .NET Framework 2.0 在 2005 年底莅临时，NDoc 委果撞上了一堵墙。微软新添加的泛型是 NDoc 尚不辅助列表上的主要问题，但也不是唯独问题。在 2005 年的一个帖子里，艳羡者 Kevin Downs 直白地说：泛型有"巨量的界限情况"，会导致 SDK 文档神志里"险些每个细节"都改了，框架自己酿成了"挪动的靶子"。那时候微软的编译器和干系框架、器具都不开源，社区艳羡者既莫得契机抓续跟进这些变化，也难以在微软居品发布后实时跟进。末端不言而谕：NDoc 对 .NET Framework 2.0 的辅助停滞了，形貌从此就没法跟上平台的进化脚步。

阿谁帖子现时仍然值得一读，因为它用作家我方的话刻画了深深的疼痛感。Kevin Downs 不是在颓靡某个缺失的功能，而是刻画一整套文档管线变得难以艳羡，全标的的。这比起阿谁简化的说法——"NDoc 只是不辅助泛型"——要好得多。

但故事莫得就此已毕。多年之后，NDoc 仍被不同的东谈主用不同的方法一次次回生。SourceForge 上出现了 NDoc3，GitHub 上还托管着一个将 NDoc 和 NDoc3 团结后的小仓库。这种坚抓在历史上专门念念吗？即使原始形貌骨子上一经死了，开导者还郁勃反复尝试回生这个想法，而不是透顶毁灭。这是否反馈了 .NET 生态的某些不良要素？

Sandcastle 的年代：微软的修起与社区的致力（2006-2015）

2006 年 7 月，就在 NDoc 官宣住手开导的几天后，微软在 CodePlex 上发布了自家用于 MSDN 文档项野心一个器具，Sandcastle。它天然比 NDoc 苍劲好多：在微软里面随同着 .NET Framework 2.0 开导而不断进化，能意会泛型等新语法，也辅助多种匡助输出神志和主题，最进攻的如故它即是微软漂亮的 MSDN 文档背后阿谁实战考试过的器具。

但一运转这个形貌就闹出个严重的信誉问题：领先在 CodePlex 上发布的时候，微软莫得提供源代码。由于 CodePlex 打着开源形貌托管网站的旗子，这个错位坐窝引起了社区方面的怀疑。InfoQ 在 2008 年的对此归来为"围绕在开源网站 CodePlex 上托管一个闭源器具 Sandcastle 的喧嚣"。在 2008 年 7 月微软最终公开了它的全部源代码，但早期的广泛一经迂缓了开源社区的信任。

为什么这很进攻：许可证的不信托性会伤害到通盘生态中其他形貌对 Sandcastle 的立场，经受如故抹杀。一个处在不信托许可证下的苍劲器具走动往不如一个法律地位明确的弱器具灵验——独特是好多开源形貌还需要定制或成就这些器具才气赢得最佳的末端。

Sandcastle 还有第二个问题：它很重，独特是在内存徒然方面。从联想上，它需要运行多个诊治管谈，这个历程中要在内存里保存通盘文档模子。这将徒然大批内容，也让器具运行得很慢。对于领有专门文档团队和高端硬件的大公司形貌，Sandcastle 不详能拼凑着。对于开源项野心开导者来熟，这相同是令东谈主防护三舍的支出。

此外，.NET Compact Framework、Silverlight、Windows Phone、Portable Class Library 等多种框架的快速涌现带来了另一个维度的复杂性，形貌文档需要处理.NET 生态的碎屑化问题。Sandcastle 也在新版块中尝试治理这些问题。

从这个时期运转，有些开源形貌逐渐迁徙到了 Sandcastle，有些则改用交易治理决策或干脆我方搭建。有些干脆通过教程和博客著作来记载 API 而不生成具体的参考文档。

多年之后，Sandcastle 莫得在微软转死后透顶隐藏。Eric Woodruff 看成 Sandcastle Help File Builder 器具的创造者从微软手工接受了这个项野喜欢慕责任。终末一个来自微软的官方版块发布于 2010 年 6 月。天然 Sandcastle 从来都不是许多社区开导者想要的阿谁绽开、轻便的谜底，ag真人但和被微软毁灭的其他器具不同，它得到了一个社区归宿。Sandcastle 今天仍然被用在一些形貌中，而不是只存在于历史注脚里的一个原因。

DocFX：里面转向（2015+）

当微软再一次尝试纠正 .NET 生态并鞭策 .NET Core 成为实验时，旧时间的文档器具更难追上这波卓越清醒了。

天然这个时期咱们还见证了其他讲话生态里文档托管作事的兴起。Read the Docs 和 Sphinx 成了那时在开源社区里最受招供的文档时间栈，而不单是是孵化它们的 Python 社区。

真理的是，ASP.NET 5 的文档网站在 docs.asp.net 时期也曾是托管在 Read the Docs 上的，用的即是 Python 和 Sphinx。Scott Hanselman 在 2015 年对这个事情作念过记载。把 .NET 文档和 Sphinx 配对的想法不是纯正的幻想，因为它如实在微软生态的某个时刻出现过一次。

不外 Sphinx 毕竟是为 Python 打造的。它对 .NET 类型、定名空间、API 结构是莫得深入意会。若是想为 Sphinx 生成高度定制化的 .NET 文档，这些问题就需要我方想想法绕以前。

在微软朝 Sphinx 再进一步之前，他们很快转向了里面的另一个形貌 DocFX，Sphinx 的诱惑力就快速消退了。

2015 年，微软在 GitHub 上持重推出了 DocFX，来担任新一代 .NET 文档器具。它辅助 Markdown 输入，高歌行器具能快速集成到 CI/CD 管谈，对 .NET 各式特点也有原生意会，如实能责任得可以。

但对许多孤苦艳羡者来说，DocFX 就显得十分节略了，不仅莫得可视化用户界面，连一个漂亮主题也莫得，这方面致使赶不上有老练生态的 Sandcastle。在居品路子图上，微软的扭捏和转弯抹角也带来了问题。2021 年用户问"docfx v3 有发布时刻表的音尘吗？"，到 2024 年才有艳羡者说"docfx v3 已看成里面形貌挪动去只辅助 Microsoft Learn"，况且关闭这个公开相关。再加上"Microsoft Learn 不再使用 docfx"的评释以及形貌转到了 .NET Foundation 旗下的变动，都让东谈主摸头不着，不知谈到底背后发生了什么。老是个奇怪的故事。

从 Sandcastle 运转，微软如实保抓了一定的绽开性，将我方里面器具放到了开源平台上托管，也如实在治理一些来自社区的新需求。然而不公开的里面路子图，对外交流的短缺，都使得这些形貌尽管时间贪念很大，却难以赢得来自开源社区的信任。即使它一时能往常责任，你也嗅觉像是在借用别东谈主的里面机器的一部分，而不是我方看成场外用户也享受到同等对待。

这种灾祸的模式在几个公开的 .NET 器具上也时时常透暴露来。Try .NET、.NET Interactive/Polyglot Notebooks 在近期都被微软关闭。他们也都在揭示这个近似的信任问题：对更庸碌的社区开导者灵验的器具，一朝不再稳妥微软里面的优先级，就失去了能源或被下线。对孤苦艳羡者来说，教养天然不是每个微软辅助的器具都注定失败。而是使用单个供应商放胆的器具那恒久都带着风险。

Lunet 的发现与 dotnet-sphinx 的出现（2026+）

Lunet 一经存在了多年，由 Alexandre Mutel 创立。它以 Scriban 为中心构建责任流并生成文档，是以如故个方便的器具。但当我防范去评估它时，我发现它在定制化方面莫得体现出独特好的联想。天然我终末的骨子论断是：我方如故想要一个更干净的通向 Sphinx 的桥梁，提供给形貌更多的定制化取舍。

Sphinx 是个被 Python、Django、Pallets、NumPy 和数千个开源形貌用的文档生成器。它有老练的主题（PyData、Furo、Alabaster），无缝集成 Read the Docs，有几十年永久的专科文档生成记载。当你发布用 Sphinx 构建的文档时，读者得到一个熟悉的、联想圣洁的体验。

多年来，好多实验性形貌出身过，像 SphinxForDotNet（2022 年 3 月归档）这么的形貌曾尝试流畅 .NET 和 Sphinx，但都莫得被庸碌采纳和抓续艳羡。它们都被归档了或在创作家转向时停滞了。

dotnet-sphinx 是流畅 .NET 到 Sphinx 生态的最新尝试，亦然我写这篇著作的初志之一。联想一个便捷天真实高歌行器具，将 API 元数据并诊治成 Sphinx 兼容的输出，在这个 AI 器具一经十分苍劲的时间花不了若干时刻。剩下的即是 API 参考文档和示例、指南内容被放在一都，交给 Sphinx 系统处理，并生成最终网站。C# SNMP 文档仓库展示了最闭幕尾，遴荐 Furo 主题，有一致的导航、内置搜索和边栏。

结语：构建韧性

.NET 文档器具的历史充满了生态分散、优先级调动等各式疲塌ag真人(AsiaGaming)，以至于开源 .NET 形貌开导者不得不我方去找治理决策。天然这亦然个很好的进化历程，杀不死你的会让你更苍劲。

大发官方网站手机app

• 年的
• 二十五
• ag真人(AsiaGaming)
• 折腾
• .NET