最近随着 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 从来都不是许多社区开辟者想要的阿谁盛开、轻便的谜底，NBA篮球下注app官方版但和被微软毁掉的其他用具不同，它得到了一个社区归宿。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 文档用具的历史充满了生态离别、优先级革新等多样迷糊，以至于开源 .NET 形势开辟者不得不我方去找处置决议。天然这亦然个很好的进化历程NBA篮球下注app官方版，杀不死你的会让你更雄壮。