Aspnetcore: 我们应该为 ASP.NET 5 文档使用什么格式？

http://shfb.codeplex.com

或者只是做一些全新的东西。

生成 GH Markdown 的良好预处理器会非常好。

+1 用于 Markdown（或 GitHub Flavored Markdown）。 它可能缺少一些功能，但它是众所周知的并且非常易于学习和使用。 我想这可能取决于托管地点的最终决定，正如您提到的一些选项。

嗨丹尼尔，
感谢您的贡献。
作为一名初级开发人员，我发现在侧边栏中将文档组织为标题很容易，类似于http://rustbyexample.com/
（恕我直言）

-1 关于制作全新的东西。
+1 在现有的东西上工作并尽可能增强。

@danroth27您能否分享更多关于您的文档需求以及您需要成熟文档系统的哪些功能的详细信息？

我认为说“使用 Markdown”太简单了。

Markdown 是 HTML 的 DSL。 就这样。 你真的会说“文档是一个已解决的问题，让我们使用 HTML！”

我们需要像 Sphinx 这样的实际文档系统。

• Markdown 无法生成 ToC。
• Markdown 无法在主题之间链接（您必须手动进行链接）
• Markdown 不能做多语言支持或多版本支持之类的事情。

我支持@ericholscher的 Read The Docs，但更具体地说是 Sphinx 和 reStructuredText。

或者使用 DOxygen 和 vNext 将永远不会被释放；）

类似于 Roslyn 或 AngularJS 的东西呢？ http://source.roslyn.codeplex.com/ https://docs.angularjs.org/api

Markdown 非常适合 GitHub 上的大多数其他项目。 +1 降价。

@shanselman ，相对链接？

我认为使用 Sphinx 会起作用。
@issafram这里的例子：
http://sphinx-doc.org/
https://docs.python.org/3/tutorial/index.html

@akoeplinger我们想要一些可以轻松生成目录并轻松跨页面链接的东西。 我们还想要可以生成多种文档格式的东西，包括 HTML、PDF 和 ePub。 文档也应该在移动设备上可读。

当您的文档有一百页时， @issafram Markdown 非常棒，很可能更少。 但是成千上万的页面和互锁的目录？ 保持附录是最新的？ 链接 ASP.NET 和 .NET 文档？ 会一团糟。

请记住，如果您希望它真正开源，从而鼓励贡献，那么系统必须尽可能简单，没有学习曲线。 Markdown 不能自己生成 ToC，但是相对简单的代码可以从 Markdown 生成 ToC。
我们 Orchard 对我们的系统非常满意，它是 Github 上的 Markdown 加上一个 Azure 站点，代码非常少（用于 Lucene 索引和搜索，以及 ToC 生成），每次推送 repo 时都会自动更新。 超级简单，熟悉的工具。
我唯一不喜欢的是缺少元数据（我们从文件名中提取标题），但也有解决方案，例如 Jeckyll 的 YAML 标头（由 Github 支持）或我自己的 Snippable 格式。

@issafram这不适用于具有大量文档和重构的大型代码库。 重命名一个类和_bye bye_ 相关链接。

_edit_：我迟到了：P

我很高兴听到 ASP.NET 文档将有数千页；）仍然，KISS。

@bleroy看看这个http://read-the-docs.readthedocs.org/en/latest/和制作它的 rST。 https://github.com/rtfd/readthedocs.org/blob/master/docs/index.rst

当然，那太好了。 只是提供我们的经验。 我知道你的规模不同。

rST 是最好的选择，动手吧。 它是 ASP.NET，拥有足够聪明的东西来更新其索引（从 ToC 甚至类列表的角度来看）可能是重中之重。

理想情况下，我会在 Build Workflow 中运行一些东西来获取从二进制文件生成的所有这些 .XML 文件，然后将它们通过处理器生成文件，然后发布到服务器。 确切的工具....我不知道。 很多都被提到了。 我建议您自己构建并开源它。 是的，是的......构建与购买的辩论，但我讨厌使用具有非托管资源的工具，例如上述一些。 无论如何，这听起来很理想......你可能有预算和时间限制，什么都没有。

@issafram如果你们最终都使用 Sphinx/RTD，那么类似于 Breathe 的方法可能是一种可行的方法： http ://breathe.readthedocs.org/en/latest/——它与 Sphinx 和 Doxygen 集成，使用Doxygen XML 文件。

@issafram听起来你在描述SHFB ...（实际上是Sandcastle ，SHFB 只是让使用起来更愉快：P）

是的，您需要一个预处理器/后处理器，您可以将文档内的相对论与 GHMD for TOC 联系起来。 对于我们的项目，我们推出了自己的项目，基本上采用 .Net doc XML 和基于约定的合并示例代码和其他用 MD 编写的静态内容。 最终结果是 HTML。

在 MD 中拥有代码和编辑静态内容将使 PR 变得容易。 我喜欢 markdown 作为一种源格式，因为它比 HTML、XML 等更干净。使审计变得容易并且非常适合源代码控制。

我们需要一个干净且简单的基于约定的 .Net 文档工具，我还没有找到，如果有的话，我很想知道。 并且很乐意为此做出贡献。

至于跨项目的可维护性和链接。 Intersphinx 是一种以语义方式执行此操作的强大方法。 它允许您对所有参考文献（无论是代码还是散文）进行编目，并跨项目显式链接到它们。

此处的文档：http: //sphinx-doc.org/latest/ext/intersphinx.html

这是我所知道的 Markdown 之类的功能所没有的功能。

同意降价不是最好的解决方案，但现在我们需要一个简单的解决方案。 Com'on 我们是开发人员，因此如果需要，我们可以扩展它。 Github 支持降价，VSO 现在最近支持从代码视图降价。 我们真的需要辩论吗？ 对不起，如果我太直接了。

降价+1

@ctsni我承认，Markdown _felt_ 就像乍一看/想到的最佳选择。 但我想得越多，就越觉得我们正试图将一个方形钉子钉入一个圆孔。

诚然，我没有一个好的选择，所以我为没有真正贡献太多而道歉，但即使在扩展 Markdown 时，我也不_感觉_我们最终会得到与现在一样漂亮、干净和整洁的 Markdown _鉴于要求_。

听起来您想以开源格式复制现有的 MSDN 文档？ 这公平吗？ 您需要一个解决方案来处理概述描述、教程、代码示例和 API 文档吗？ 或者它是其中的一个子集？

我不相信有一个解决方案，更多的是可以组合输出的工具集合。 我可以看到 ReadTheDocs 正在做什么 - 将多个来源整合到一组连贯的文档中。 所以 Markdown 是对部分解决方案（即描述和教程）的有效答案，但不是全貌？

开放式问题：是否可以直接从 Markdown 中提取附录和 TOC？ 对我来说似乎不太难？ 我有偏见。 我没有在一个有数千页的系统上工作过......对不起@shanselman ，我真的无法贡献我所知道的智慧。

@craignicol对我来说，任何低于当前 MSDN 文档的内容都会让我大失所望。 我总是告诉大家一些最好的文档（在结构、措辞和有关它的所有方面）可以在 MSDN 上找到。 我看过很多文档，但大多数（如果不是全部的话）都没有接近“MSDN 质量”（当然恕我直言）。 话虽如此：一个很大的因素当然是 MSDN 文档背后的人对 MSDN 的实际内容非常关心； 结构、布局、设计和你拥有的东西排在第二位。

也许是切线的，但有类似dash的东西会非常好。 Web 开发发展得如此之快，新技术相互影响，以至于我发现自己在谷歌上到处搜索信息。 能够访问可以通过一些击键调用的单个包含位置中的所有内容非常有用。 对于 Linux 和 Windows，也有类似的努力http://zealdocs.org/ 。

@craignicol同意，目标是拥有开源且更易于维护和保持最新的 MSDN 质量文档。

@ciriarte支持将 Sphinx 文档翻译成 Dash： https ://pypi.python.org/pypi/doc2dash——我们已经查看了 RTD.org 上的自动 Dash 集创建，但目前没有部署它。

我认为@shanselman在上面说得最好——Markdown 不是答案，而 HTML、Word 或 .txt 才是答案。 Markdown 主要是一个演示描述 - 需要的是生成 Markdown（或 HTML、Word 文档、.txt 文件等）的东西

我想我的问题是您从哪里看到这些内容？ 会手写吗？ 从代码自动生成？ 嵌入评论？

我同意@craignicol的一组工具，用于将自动生成的内容与“静态”GH Markdown 页面合并，用于人造样本和编辑内容在汇编 XML 中无效。 然后输出结果可能是 GHPages、PDF 或其他任何内容上的静态 html。
如果代码重命名/重构，预处理器可以检测到任何孤立的静态内容
语言支持基本上可以是与中性结构相同的可选文件夹。 然后，未翻译的文档可以退回到中立或通过 Bing 翻译。

回顾最初的建议，我会同意@danroth27关于 markdown 的格式和 readthedocs 的构建。 谢谢。

readthedocs.org + Sphinx 的灵活性可以允许与 MSDN 等价，即使它不适合它。

@ciriarte MSDN 阅读器的可导出档案也可能支持这一点。

@jalcine @ericholscher听起来很棒。

@RobThree我希望能够说服当前维护文档的团队转向新格式，否则这个练习不值得做。

@ctsni有可能 - 我在 python 中编写了一个降价 ToC 解析器，它获取文件列表并生成一个 ToC。 棘手的部分是注释源文件，以便解析器知道要提取什么来生成 ToC 和附录。 中间格式，无论是 Markdown 还是 rST，都无关紧要，关键是正确获取元数据。

查看 MSDN 文档，对超链接最重要的元数据的两个关键部分是 API 挂钩，允许遍历代码，以及创建主题以包含 API、教程、和架构信息。 如果 API 部分做得对，我相信其余的内容可以适应。 我喜欢 Dash 的想法，但我认为 ReadTheDocs 和 Sphinx 是我所见过的最接近我喜欢 MSDN 的东西，但我认为它们需要适应处理 MSDN 拥有的丰富主题和教程结构。

我确实想知道这整个概念。 我的意思是，我喜欢开源文档链并让社区参与的想法，但在 MSDN 之外做这件事让我有点胆怯。 从看起来（并且可能是）.NET 的开始，我们已经到 MSDN 获取有关任何 Microsoft API 的规范参考。 从 WinForms 到 WebForms，它都在一个地方，很好地交叉引用和一致的格式。 我不禁想知道从这项努力中获得的东西是否会提供足够的好处来抵消碎片化和一致性的损失。 并不是说这不完全值得，而且大概这些讨论已经发生了，但值得深思。

+1 狮身人面像

我真的很喜欢 readthedocs 格式和工具，它们适用于许多项目。 不要重新发明轮子。 降价就好了。 我认为如果你不能用降价来描述它，那么你就是在尝试做一些太复杂的事情。 如果格式和摩擦水平低，我会很乐意做出贡献。 MSDN wiki 差不多到了那里，但大部分都关闭了，它变成了旧内容的贫瘠荒地。 PHP 社区似乎在他们的文档系统上做得相当好（尽管他们的评论有时会陷入困境）。 我认为使用降价保持简单是可行的，但可能需要某种索引/生成工具用于“主文档”或将其组合在一起并保持同步的东西。 几乎就像数千个降价代码片段/文档的依赖构建系统。

我认为 Markdown 用于文本片段。 用于元数据的 Yaml 前端或 json 文件。 具有可扩展插件模型的基于 .NET 的自定义处理器，可以轻松为 TOC 和表格等花哨的东西添加语法。或者只使用 rst，与 Markdown 非常相似。

只需将 MSDN 开源。 除非它是一团糟:)

@somedave不了解你，但我发现在 MSDN 上找到内容越来越难，尤其是关于非当前框架的高级架构文档。 将文档链接到代码，以及所有可用的开源和版本控制是一个巨大的改进。

我们真的想要新微软的另一个 MDSN 吗？ 生成的大部分文档都是浪费时间。 它需要的是叙述和示例，但经常缺少这些，只留下我已经从类型系统中获得的基本信息。 通过轻松访问源代码，我们现在可以找出某些东西到底做了什么。 文章、解释和使用测试示例要好得多，特别是如果根据需求创建，例如堆栈溢出问题。

@danroth27 ，您是在谈论 javadoc/xmldoc 文档，还是一般的文档？ 即这个http://www.asp.net/aspnet/overview/authentication-and-identity vs https://msdn.microsoft.com/en-us/library/system.web.mvc.ivalueprovider (v=vs. 118).aspx?

Dgeni https://github.com/angular/dgeni

绝对是 HTML，但可以在本地使用它——假设将它安装在本地 IIS（或仅在本地）上。

请以 Sandcastle 和 SHFB 管道为基础，并帮助使其变得更好（更简单和“开源友好”）。 可以添加对降价创作（针对概念性内容）和渲染的支持（已经朝这个方向进行了一些开始）。
支持流行的（SHFB 下载量为 50 万次）基于 .NET 的工具有很多狗粮价值。 习语确实从工具泄漏到项目本身。 例如，对于 .NET，支持多语言代码片段非常有价值，因此 VB.NET 和 F# 可以作为平台上的可行语言进行维护。 Sandcastle 和 MSDN 风格的输出在这方面做得很好。

reStructuredText 的问题在于它有点像 Markdown，但不完全是。 因此，它成为另一种学习形式。 SHFB 目前可以完成工作，但体验并不愉快。 有东西总比没有好，EWoodruff 非常感谢它让这个东西保持活力和更新了这么久。

从 .NET 开发人员的角度来看，仍然需要/想要一个非常好的 .NET 开源文档生成工具。 在我看来，它最好是一个允许用 Markdown 编写长格式文本的工具，因为它是已知且使用起来令人愉快的东西。

我知道 MS 团队可能想要启动并运行一些东西以将 asp.net 5 发布出去，但这触及了开发人员长期存在的痛苦。

我的建议之一是与http://commonmark.org/合作开发 commonmark 模块并着眼于增强https://github.com/Knagis/CommonMark.NET 之类的东西。

否则，至少在第一次发布后对替换文档系统持开放态度，这样社区就不会被一些使用起来有很多摩擦的东西困住......再次。

也是另一个痛点。 文档应该以可以在本地使用的某种格式提供。 有些人在未连接到 Internet 的系统上工作，而离线文档可以挽救生命。 我不得不在这样的环境中工作，离线文档非常宝贵。

@ryanbnl我们正在为 API 参考文档和概念内容寻找解决方案。

@michaelherndon我完全同意.NET 需要一个好的开源文档生成工具！ 您也是正确的，我们需要为 ASP.NET 快速启动和运行某些东西。 如果出现社区支持的基于 .NET 的文档，我们当然愿意采用它。 我们也同意，必须有一种离线访问文档的方法。

好的，很清楚 :) 对于 API 文档，doxygen 值得一看。 它真的很强大，并且可以生成类图（在某些情况下可能非常有用）。 去年我对 doxygen/sandcastle 做了详细的比较，如果有帮助，我可以给你发一份吗？ 它包含大量示例 + 分步安装指南（doxygen 很难安装）；）

似乎一个问题是保持文档开源，以便其他人可以做出贡献。 其次是用于生成和维护此类文档的工具。
我们能不能有一个开源的工具，允许为最终上传生成 html/GHMD。 任何需要贡献的人都可以使用此工具并根据他们在 github 上的访问级别修改页面。 工具应该是灵活的，因此它可以用于小型或大型项目。 该工具可以是为任何项目生成文档的 VS 扩展，基本模板的示例文档可以是可选的，例如新项目中的当前身份验证选项。

@farrukhsubhani该工具可能不应该依赖于 VS：如果我们希望 Mac 和 Linux 用户使用并为 ASP.NET 做出贡献，那么该工具必须是跨平台的，并且不需要大量安装。

我注意到现在来源中的文档注释很少。 尽管它因文件而异。 是否已决定将其用作参考文档的输入，还是由单个开发人员决定？

无论这次讨论产生什么结果，我都赞成至少在未来仍然拥有它，编译器支持创建这些 XML 文件（或插入 IntelliSense 的其他格式）以及今天的编辑和突出显示体验，这特别可爱Visual Studio 中的罗斯林。

也许其他人强烈反对，但我特别不喜欢编辑 /* */ 风格的评论和一系列对齐的 *。 请告诉我我不用担心；）

@danroth27

只是一些想法，并提前感谢您至少阅读和思考这一点。

Restructuredtext 看起来像 PITA 注入简单的东西，如链接或标题。 我会在一周中的任何一天接受 Javadoc 代码注释或只是香草 html。

============
h1
============

***************
h2
***************

h3
------------------

check out the _aspnet homepage.

.. _aspet: http://www.aspnet.com/

我想请求 aspnet 在内部讨论与社区合作，在 .net 文档工具上设置一些目标/spes，并可能提供一些创造性的激励措施，如认可或类似的东西。 我还请大家讨论通过 .NET 基础设置项目。 这也可以作为一个像样的代码实习生/暑期项目，供 cs 学生从事，因为它很可能涉及创建解析器。

这不是针对您或任何人的，但是在开发周期的后期才开始发布和思考这个问题，因为它迫使你们陷入困境，使用一些有效的东西，但不是很受欢迎的东西所有场景，包括低准入门槛。

假设地说，早先与社区交谈可能至少已经产生了一个可以使用的工具，并且它可以在所有 aspnet 团队的辛勤工作之上并行构建，作为 dogfooding aspnet 5 的一个很好的例子。

话虽如此，如果现在开始，它可能已经准备好供 .NET core 5 使用。

@ericwj所有公共 API 都需要¹对它们进行 XML 文档注释。 然而，在项目的早期，我们放宽了这一要求，因为在我们知道会发生重大变化的 API 上编写大量文档被认为在很大程度上是浪费精力。 然而，在过去几个月的所有提交中，应该有大量的文档存在。 确实还有很多漏洞，但是提供这个文档是团队的义务。 在修补文档时，我们倾向于专注于我们认为开发人员会访问的更重要的 API，并将更深奥的 API 归为文档较少的状态（我们仍然希望有朝一日能够填补）。

^{1 个}必需的_形容词_

不是可选的东西。
也可以表示在 XML 文档注释的上下文中_is_ 可选的东西。

@michaelherndon BTW 这个项目已经是 .NET Foundation 的一部分。

@Eilon上下文是在谈论添加一个 .net 文档工具，而不是 aspnet 5。

@michaelherndon啊，明白了，谢谢！

@shanselman @danroth27 ，我上周五通知了我的经理，这个人已就该线程联系了 MSDN Principal Group PMs。 他们应该就您的文件事宜与您联系。 祝你今天过得愉快。

@michaelherndon我同意标题语法有点冗长。 另一种一般情况是链接到文档中的函数或页面，这就是 RST 的亮点：

More Info
=========

This function wraps :func:`bar`, 
more info in :doc:`bar-like-functions` or on our `website <http://www.aspnet.com>`_.

在 Markdown 中做类似的事情：

### More Info

This function wraps [bar](func:bar), 
more info in [Bar Like Functions](bar-like-functions.md) or on our [website](http://www.aspnet.com).

我在这里看不出有很大的根本区别。 带有 Sphinx 的 RST 为您提供了大量有价值的参考功能，这些功能可能会丢失，或者在 Markdown 案例中以非语义方式链接到 URL 或 HTML 文档。

沿着这些思路的另一个有趣的花絮是关于如何以兼容的方式编写 RST 和 MD 的文档： https://gist.github.com/dupuy/1855764。 Markdown 通常支持 RST 样式的标题，因此标题样式适用于两者。

您还可以配置 Sphinx 或其他工具来理解带有扩展名的基本 Markdown 语法（如果它是一个显示停止器）。

我记得大约 18 个月前在 MVP Submit 的 OSS 面板上说过，.NET 中的文档没有好的选择：stuck_out_tongue_closed_eyes：

我真正希望看到的是一种从 .NET XML 文档生成 markdown 或 rst 以及目录的方法。 然后可以将其加载到 readthedocs 或 github wiki 之类的东西中。

Sandcastle 已经拥有大量用于阅读 .NET XML 文档的代码，并且可以使用新的样式和输出类型进行扩展。 你可以以此为基础。

我如何查看这个线程并弄清楚结论是什么，是否做出了决定，如果是，它是什么？

https://github.com/aspnet/Docs

你们为什么不使用DocFX？

当我们开始为 ASP.NET 5 编写文档时，docfx 项目仍处于开发的早期阶段。 Sphinx仍然是一个更加成熟且功能丰富的文档框架。 除此之外， Read the Docs提供了一个非常好的文档托管解决方案。

也就是说，我们支持将 docfx 作为 .NET 的文档解决方案所做的努力，很高兴看到

当 docfx 似乎是 MSDN 正在使用的东西时，从两个不同的方向走出大门似乎是一种耻辱，至少通过内置主题。

@simonmurdock docfx（尚）不支持生成离线文档，例如 PDF

是的@cocowalla我对工会的状态一直在不断变化与文档。 我现在正在用 sphinx 写我的文章，但没有真正好的方法来生成 sphinx 集成的 API 文档。

目前的计划是所有文章的 Sphinx 和 DocFX 输出的单独站点，直到 Sphinx ApiDocs 看起来更好一点。

@simonmurdock下面是我们目前使用 docfx 和 Sphinx autoapi扩展的组合为 ASP.NET 生成 API 参考文档所做的工作： https://github.com/aspnet/apidocs。 它仍然有点粗糙，但我们正在与 Read the Docs 人员一起进行一系列改进。

@danroth27 RsT 投了这么多票，但是你最终选择了 MD 吗？ 当我在https://docs.microsoft.com/en-us/aspnet/core/的任何页面上单击 EDIT 时，我会在 GitHub 上看到 MD 源文件。
那么为什么是医学博士？

我们在 ASP.NET Core 和 EF Core 文档中使用 RST 和http://readthedocs.com有一段时间了，但最近微软在http://docs.microsoft.com建立了自己的文档基础架构，所以我们搬到了与此一致。 虽然 markdown 不像 reStructuredText 那样成熟，但它对更广泛的受众来说更为熟悉。 出于这个原因，即使阅读文档也支持这两种格式。

@danroth27这是否意味着微软已经创建了自己的使用降价的非开源文档生成器/引擎？ https://docs.microsoft.com 后面还有什么？

这是否意味着微软已经创建了自己的使用降价的非开源文档生成器/引擎？

不。https ://docs.microsoft.com 背后的文档引擎是DocFX ，它基于 .NET 构建并且是完全开源的。 它的格式确实使用了降价。

你好

我可能会有点晚发布这个。

我只是想知道是否有一个 api 或框架或工具可以让我们创建一个文档站点，比如 https://docs.microsoft.com 的站点？ 我个人喜欢微软文档的呈现方式， @danroth27提到了所使用的引擎 DocFX，我只想知道网站本身是从头开始完成的，还是有模板或包我们可以用于生成相同的外观和感觉？ 不完全相同，但我们可以修改:)

谢谢！
裘德·阿尔基萨。

我对DocFx了解得越多，我就越喜欢它——很快就会试一试。

我们如何在内部创建自己的文档网站，例如https://docs.microsoft.com/而无需重新发明轮子？ 我们对 python 文档使用托管的 readthedocs，对 c/c++ 文档使用托管的 doxygen。

将所有 API 文档集中在一个屋檐下的最佳方法是什么？ 从阅读这个线程来看，似乎很多人使用 sphinx/readthedocs，但是您如何将您的 .XML 文档转换为这些工具的正确格式？