Aspnetcore: ASP.NET 5のドキュメントにはどの形式を使用する必要がありますか？

http://shfb.codeplex.com

または、何か新しいものを作成します。

GHマークダウンを生成する優れたプリプロセッサは優れています。

Markdown（またはGitHub Flavoured Markdown）の場合は+1。 一部の機能が不足している可能性がありますが、非常によく知られており、習得と使用が非常に簡単です。 あなたがいくつかのオプションを述べたように、それはそれがどこでホストされるかについての最終決定に依存するかもしれないと思います。

こんにちはダニエル、
ご協力いただき、ありがとうございます。
ジュニア開発者として、このhttp://rustbyexample.com/のように、サイドバーでドキュメントをタイトルとして整理するのは簡単だと思います。
（私見では）

-1つは真新しいものを作ることです。
+1して、既存のものに取り組み、可能であれば強化します。

@ danroth27ドキュメンテーションのニーズと、成熟したドキュメンテーションシステムのどの機能が必要かについて、もう少し詳しく教えていただけますか？

「Markdownを使う」と言うのは単純すぎると思います。

MarkdownはHTML用のDSLです。 それで全部です。 「ドキュメントは解決された問題です。HTMLを使用しましょう！」と本当に言いますか？

Sphinxのような実際のドキュメントシステムが必要です。

• Markdownは目次を生成できません。
• マークダウンはトピック間をリンクできません（手動でリンクを行う必要があります）
• Markdownは多言語サポートや多バージョンサポートのようなことはできません。

@ericholscherのReadThe 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は、ドキュメントが100ページ、おそらくそれより少ない場合に最適です。 しかし、何千ものページと連動する目次はありますか？ 付録を最新の状態に保ちますか？ ASP.NETと.NETのドキュメントをリンクしますか？ それは混乱するでしょう。

これを本当にオープンソースにし、貢献を促すものにしたい場合は、システムをできるだけシンプルにし、学習曲線をなくす必要があることに注意してください。 Markdownはそれ自体でToCを生成することはできませんが、比較的単純なコードでMarkdownからToCを生成できます。
Orchardのシステムは、GithubのMarkdownに加えて、リポジトリがプッシュされるたびに自動更新されるコードがほとんどないAzureサイト（Luceneのインデックス作成と検索、およびToC生成用）に非常に満足しています。 超シンプルで使い慣れたツール。
私が気に入らないのはメタデータの欠如（ファイル名からタイトルを抽出する）だけですが、JeckyllのYAMLヘッダー（Githubでサポートされている）や私自身のSnippable形式などの解決策もあります。

@issaframこれは、たとえば大量のドキュメントやリファクタリングを使用する巨大なコードベースではうまく機能しません。 クラスと_byebye_相対リンクの名前を変更します。

_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またはクラスリストの観点からさえ）はおそらく最優先事項です。

理想的には、ビルドワークフローで何かを実行して、バイナリから生成されたすべての.XMLファイルを取得し、それらをプロセッサに通してファイルを生成し、サーバーに公開します。 正確な工具....私には手がかりがありません。 多くが言及されています。 独自のオープンソースを作成することをお勧めします。 はいはい...ビルドと購入の議論がありますが、上記のような管理されていないリソースを持つツールを使用するのは嫌いです。 とにかくそれは理想的に聞こえます...あなたはおそらく予算と時間の制約がありますが、そうではありません。

@issaframすべてがSphinx / RTDを使用することになった場合、Breatheに沿った何かが実行可能なアプローチになる可能性があります：http： //breathe.readthedocs.org/en/latest/-これは、Sphinx＆Doxygenとの統合です。 DoxygenXMLファイル。

@issaframあなたがSHFBを説明しているように聞こえます...（実際にはSandcastle 、SHFBは：Pを使用することをより楽しいものにします）

はい、プリプロセッサ/ポストプロセッサが必要です。ドキュメント内の相対性理論をGHMD forTOCにリンクできます。 私たちのプロジェクトでは、基本的に.Net doc XMLを採用し、MDで記述されたサンプルコードやその他の静的コンテンツとマージされたコンベンションベースを採用しました。 最終結果はHTMLです。

MDにコードとエディトリアルの静的コンテンツがあると、PRが簡単になります。 ソース形式としてのマークダウンについて私が気に入っているのは、HTML、XMLなどよりもクリーンであるということです。監査が簡単になり、ソース管理に最適です。

.Netには、クリーンでシンプルなコンベンションベースのドキュメントツールが必要です。通知が必要な場合は、見つかりませんでした。 そして、それに貢献できれば幸いです。

保守性とプロジェクト間のリンクについて。 Intersphinxは、セマンティックな方法でそれを行うための強力な方法です。 これにより、すべての参照（コードまたは散文）をカタログ化し、プロジェクト間で明示的にリンクすることができます。

ここのドキュメント： http ：//sphinx-doc.org/latest/ext/intersphinx.html

これは、Markdownのようなものには私が知っている方法ではまったく持っていない種類の機能です。

マークダウンは最善の解決策ではないことに同意しましたが、今のところ、単純な解決策が必要です。 Com'onは開発者なので、必要に応じてこれを拡張できます。 Githubはマークダウンをサポートしていますが、VSOは最近コードビューからのマークダウンをサポートするようになりました。 本当に議論が必要ですか。 率直すぎてごめんなさい。

マークダウン+1

@ctsni私は認めます、Markdownは一見/思考の最良の選択のように_感じました_。 しかし、考えれば考えるほど、四角いペグを丸い穴に打ち込もうとしているように感じます。

確かに良い選択肢がないので、実際にはあまり貢献していないことをお詫びしますが、Markdownを拡張しても、今と同じようにきれいで、きれいで、きちんとしたMarkdownになってしまうことはありません。要件_。

既存のMSDNドキュメントをオープンソース形式で複製したいようですね。 それは公平ですか？ 概要の説明、チュートリアル、コードサンプル、APIドキュメントを処理するためのソリューションが必要ですか？ それともそのサブセットですか？

解決策が1つあるとは思いません。それは、出力を組み合わせることができるツールのコレクションです。 ReadTheDocsが何をしているのかがわかります。複数のソースを1つの一貫したドキュメントセットにまとめています。 したがって、Markdownはソリューションの一部（つまり、説明とチュートリアル）に対する有効な答えですが、全体像ではありませんか？

未解決の質問：マークダウンから直接付録と目次を抽出することは可能ですか？ 私には難しすぎませんか？ 私は偏見があります。 私は何千ページものシステムに取り組んだことがありません...申し訳ありませんが@shanselman 、私は本当に私が知っている以上の知恵に貢献することはできません。

@craignicol現在のMSDNドキュメントよりも少ないものは、私にとっては大きな失望になります。 私は常に、MSDNにある最高のドキュメント（構造、文言、およびそれに関するすべて）のいくつかをすべての人に伝えています。 私はたくさんのドキュメントを見てきましたが、すべてではないにしても、ほとんどが「MSDN品質」（もちろんIMHO）にさえ近づいていません。 そうは言っても、大きな要因は、もちろん、MSDNドキュメントの背後にいる人々がMSDNの実際の_コンテンツ_を非常によく世話していることです。 構造、レイアウト、デザイン、そして何を持っているかが2番目になります。

おそらく接線ですが、ダッシュのようなものがあると非常に便利です。 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が答えになります。 マークダウンは主にプレゼンテーションの説明です。必要なのは、マークダウン（または、HTML、Word文書、.txtファイルなど）を生成するためのものです。

私の質問は、そのコンテンツがどこから来ていると思いますか？ 手書きになりますか？ コードから自動生成されますか？ コメントに埋め込まれていますか？

@craignicolは、自動生成されたコンテンツを、アセンブリXMLでは利用できない人工サンプルおよび編集コンテンツの「静的」GHマークダウンページとマージするためのツールのコレクションに同意します。 結果は、GHPages、PDFなどの静的HTMLになる可能性があります。
コードの名前が変更/リファクタリングされた場合、プリプロセッサは孤立した静的コンテンツを検出できます。
言語サポートは、基本的にニュートラルと同じ構造のオプションのフォルダーである可能性があります。 翻訳されていないドキュメントは、ニュートラルにフォールバックするか、Bing翻訳を通過する可能性があります。

元の提案を振り返ると、フォーマットのマークダウンとビルドのreadthedocsについて@ danroth27に同意するでしょう。 ありがとう。

readthedocs.org + Sphinxの柔軟性により、MSDNに近づきにくい場合でも、MSDNとの同等性を実現できます。

@ciriarteこれは、MSDNリーダー用のエクスポート可能なアーカイブでもサポートされる可能性があります。

@ jalcine @ ericholscherは素晴らしいですね。

@RobThree現在ドキュメントを管理しているチームが新しい形式に移行するように説得できることを願っています。そうでない場合、この演習を行う価値はありません。

@ctsniそれは可能です-私はPythonでマークダウンToCパーサーを作成しました。これは、ファイルのリストを取得してToCを生成します。 トリッキーな部分は、パーサーがToCと付録を生成するために何を抽出するかを認識できるように、ソースファイルに注釈を付けることです。 MarkdownであろうとrSTであろうと、中間フォーマットは無関係であり、重要なメタデータを正しく取得しています。

MSDNのドキュメントを見ると、ハイパーリンクで最も重要な2つのメタデータは、コードのトラバースを可能にするAPIフックと、API、チュートリアル、およびアーキテクチャ情報。 APIの部分が正しく行われていれば、残りのコンテンツはそれに合わせて調整できると確信しています。 Dashのアイデアは好きですが、ReadTheDocsとSphinxは、MSDNについて私が見たものに最も近いと思いますが、MSDNの豊富なトピックとチュートリアル構造を処理するように適合させる必要があると思います。

私はこの全体の概念について疑問に思います。 つまり、ドキュメントチェーンをオープンソーシングし、コミュニティを巻き込むというアイデアは気に入っていますが、MSDNの外部でそれを行うと意欲が高まります。 .NETの始まりのように見える（そしてそうであったかもしれない）ことから、MicrosoftAPIの標準的な参照のためにMSDNに行きました。 WinFormsからWebFormsまで、すべてが1つの場所にあり、適切に相互参照され、一貫してフォーマットされています。 この努力から得られたものが、断片化と一貫性の喪失を上回るのに十分な利益をもたらすのだろうかと思わずにはいられません。 それが完全に価値があるとは言わない、そしておそらくこれらの議論はすでに行われているが、思考の糧である。

スフィンクスの+1

私はreadthedocsのフォーマットとツールを本当に掘り下げており、それらは多くのプロジェクトで非常にうまく機能します。 車輪の再発明をしないでください。 値下げは問題ありません。 マークダウンで説明できない場合は、複雑すぎることをしようとしていると思います。 フォーマットと摩擦レベルが低ければ、私は喜んで貢献したいと思います。 MSDN wikiはそこに到達するようなものでしたが、ほとんどが閉鎖され、古いコンテンツの不毛の荒れ地になりました。 PHPコミュニティは、ドキュメントシステムでかなりうまくやっているようです（ただし、コメントがうさぎの穴に落ちることもあります）。 マークダウンでシンプルに保つことはうまくいくと思いますが、おそらく「マスタードキュメント」用の何らかのインデックス/生成ツール、またはそれをまとめて同期を保つための何かが必要です。 何千ものマークダウンスニペット/ドキュメントの依存関係ビルドシステムのようなものです。

テキストフラグメントのマークダウンだと思います。 メタデータ用のYamlフロントマターまたはjsonファイル。 TOCやテーブルなどの凝ったものの構文を簡単に追加するための拡張可能なプラグインモデルを備えたカスタム.NETベースのプロセッサ。または、Markdownと十分に似たrstを使用します。

MSDNをオープンソースにするだけです。 それが混乱していない限り:)

@somedaveはあなたのことを知りませんが、MSDNでコンテンツ、特に最新ではないフレームワークに関する高レベルのアーキテクチャドキュメントを見つけるのはますます難しくなっています。 ドキュメントをコードにリンクし、利用可能なすべてのオープンソースをバージョン管理下に置くことは、大幅な改善です。

新しいMicrosoftの別の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をドアから出荷するために何かを立ち上げて実行したいと考えていることは知っていますが、これは開発者が感じる長年の苦痛に触れています。

私の提案の1つは、 http： //commonmark.org/と連携してcommonmarkモジュールを開発し、 https：//github.com/Knagis/CommonMark.NETのようなものを拡張することを検討することです。

それ以外の場合は、少なくとも最初のリリース後にドキュメントシステムを交換することを受け入れて、コミュニティが使用するのに多くの摩擦があるものにとらわれないようにします。

また、別の問題点。 ドキュメントは、ローカルで使用できる形式で利用できる必要があります。 インターネットに接続されていないシステムで作業している人がいて、オフラインのドキュメントは命の恩人です。 私はそのような環境で作業しなければならず、オフラインのドキュメントは非常に貴重です。

@ryanbnlAPIリファレンスドキュメントと概念コンテンツの両方のソリューションを探しています。

@michaelherndon .NET用の優れたオープンソースドキュメント生成ツールが必要であることに完全に同意します！ また、ASP.NET用に何かをすばやく起動して実行する必要があることも正しいです。 コミュニティがサポートする.NETベースのドキュメントが登場した場合、もちろんそれを採用することもできます。 また、ドキュメントにオフラインでアクセスする方法があることが要件であることに同意します。

わかりました、それは明らかです:) APIドキュメントの場合、doxygenを調べる価値があります。 これは非常に強力で、クラス図を生成できます（特定の状況では非常に貴重な場合があります）。 昨年、doxygen / sandcastleの詳細な比較を行いましたが、役立つ場合はコピーをお送りしますか？ たくさんの例とステップバイステップのインストールガイドが含まれています（doxygenのインストールは難しいです）;）

1つの問題は、他の人が貢献できるようにドキュメントをオープンソースに保つことのようです。 2つ目は、そのようなドキュメントを作成および保守するために使用されるツールです。
オープンソースであり、最終的なアップロードのためにhtml / GHMDを生成できるツールを用意することはできませんか。 貢献する必要がある人は誰でもこのツールを使用して、githubのアクセスレベルに基づいてページを変更できます。 ツールは、小規模または大規模なプロジェクトで使用できるように柔軟である必要があります。 このツールは、任意のプロジェクトのドキュメントを生成するVS拡張機能であり、基本テンプレートのサンプルドキュメントは、新しいプロジェクトの現在の認証オプションのようにオプションにすることができます。

@farrukhsubhaniツールはおそらくVSに依存しないはずです。MacおよびLinuxユーザーがASP.NETを使用して貢献できるようにする場合、ツールはクロスプラットフォームである必要があり、大規模なインストールは必要ありません。

現在、ソースにドキュメントのコメントがほとんどないことに気づいています。 ファイルごとに異なりますが。 それをリファレンスドキュメントの入力として使用することについて決定がありましたか、それとも個々の開発者次第でしたか？

この議論が何をもたらすにせよ、少なくとも将来的には、それらのXMLファイル（またはIntelliSenseにプラグインする別の形式）を作成するためのコンパイラーのサポートと、今日の編集とハイライトの経験で特にかわいいことに賛成して話したいと思いますVisualStudioのRoslyn。

他の人は激しく反対するかもしれませんが、私は特に/ * * /スタイルのコメントと一連の整列された*の編集が嫌いです。 心配する必要はないと言ってください;）

@ danroth27

少なくともこれを読んで考えてくれて、事前にいくつかの考えと感謝を。

Restructuredtextは、リンクや見出しなどの単純なものを挿入するPITAのようです。 私は、Javadocコードのコメント、または単にバニラhtmlを、この曜日に受け取ります。

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

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

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

check out the _aspnet homepage.

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

aspnetが、.netドキュメントツールでいくつかの目標/速度を設定することについてコミュニティと協力することについて社内で話し合い、認識などの創造的なインセンティブを提供することを要求したいと思います。 また、.NETFoundationを介したプロジェクトの設定についても皆さんに話し合っていただきたいと思います。 これは、パーサーの作成を伴う可能性が最も高いため、csの学生が取り組むプロジェクトのような適切なインターン/夏のコードとしても役立つ可能性があります。

これはあなたや特に誰かに向けられたものではありませんが、開発サイクルの後半で、これについて投稿して考え始めるのは遅いです。参入障壁が低いことを含むすべてのシナリオ。

仮に、以前にコミュニティと会話したことで、少なくとも今では使用可能なツールが作成された可能性があり、ドッグフーディングaspnet 5の良い例として、すべてのaspnetチームの努力に加えて並行して構築できた可能性があります。

そうは言っても、これが今開始されていれば、たとえば.NET Core5を使用する準備ができている可能性があります。

@ericwjすべてのパブリックAPIには、XMLドキュメントコメントが必要です¹ 。 ただし、プロジェクトの早い段階で、大幅に変更されることがわかっているAPIに関するドキュメントを大量に作成することは、ほとんど無駄な作業と見なされていたため、この要件を緩和しました。 ただし、過去数か月のすべてのコミットには、かなりの量のドキュメントが存在するはずです。 確かにまだ多くの穴がありますが、このドキュメントを提供するのはチームの義務です。 ドキュメントにパッチを適用するとき、開発者がアクセスすると思われるより重要なAPIに焦点を当て、より難解なAPIを文書化されていないステータスに任せる傾向があります（いつか記入することを望んでいます）。

¹必要な_形容詞_

オプションではないもの。
XMLドキュメントコメントのコンテキストでオプションであるという意味もあります。

@michaelherndonところで、このプロジェクトはすでに.NETFoundationの一部です。

@Eilonコンテキストは、aspnet5ではなく.netドキュメントツールの追加について話していました。

@michaelherndonああ、ありがとう！

@shanselman @ danroth27 、先週の金曜日にマネージャーに通知しました。このスレッドについて、MSDNプリンシパルグループのPMに連絡しました。 彼らはあなたの文書の問題についてあなたに連絡するべきです。 良い1日を。

@michaelherndonヘッダー構文がもう少し冗長であることに同意します。 もう1つの一般的なケースは、関数またはドキュメント内のページへのリンクです。これは、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ドキュメントに非セマンティックな方法でリンクされる貴重な参照機能の大規模な配列を提供します。

これらの行に沿ったもう1つの興味深い情報は、互換性のある方法でRSTとMDを作成する方法に関するこのドキュメントです： https：//gist.github.com/dupuy/1855764。 Markdownは一般的にRSTスタイルのヘッダーをサポートしているため、ヘッダースタイルは両方で機能します。

ショーストッパーの場合は、拡張機能を備えた基本的なMarkdown構文を理解するようにSphinxまたはその他のツールを構成することもできます。

約18か月前にMVPSubmitのOSSパネルで、.NETにドキュメントを作成するための適切なオプションがなかったと言ったことを覚えています：stuck_out_tongue_closed_eyes：

私が本当に見たいのは、.NETXMLドキュメントからマークダウンまたは最初と目次を生成する方法です。 次に、readthedocsやgithubwikiなどにロードできます。

Sandcastleには、.NET XMLドキュメントを読み取るための大量のコードがすでにあり、新しいスタイルと出力タイプで拡張可能です。 その上に構築することができます。

このスレッドをどのように見て、結論が何であったか、決定が下されたかどうか、もしそうならそれが何であったかを理解するにはどうすればよいですか？

https://github.com/aspnet/Docs

なぜあなたたちはDocFXを使用しないのですか？

ASP.NET 5のドキュメントを書き始めたとき、docfxプロジェクトはまだ開発の初期段階にありました。 Sphinxはまだはるかに成熟しており、豊富なドキュメントフレームワークを備えています。 その上、 Read theDocsは本当に素晴らしいドキュメントホスティングソリューションを提供します。

とは言うものの、私たちは.NETのドキュメントソリューションとしてのdocfxの取り組みを支援しており、 docfxがオープンソースになったことを見るとワクワクします。 APIリファレンスドキュメントにdocfxを使用することをすでに計画しており、成熟するにつれてdocfxに移行する予定です。

少なくとも組み込みのテーマを使用して、docfxがMSDNが使用しているものであるように見える場合、ゲートから2つの異なる方向に進むのは残念なことのようです。

@simonmurdock docfxは、PDFなどのオフラインドキュメントの生成を（まだ）サポートしていません

ええ@cocowalla私はドキュメンテーションで一般教書演説について永遠に流動的です。 私は現在、スフィンクスで記事を書いていますが、スフィンクスに統合されたAPIドキュメントを生成するための本当に良い方法はありません。

現在の計画は、Sphinx ApiDocsが少し見栄えが良くなるまで、すべての記事についてはSphinxであり、DocFXの出力については別のサイトです。

@simonmurdockこれは、docfxとSphinx autoapi拡張機能の組み合わせを使用してASP.NETのAPI参照ドキュメントを生成するために現在行っていることです： https：//github.com/aspnet/apidocs。 まだ少し荒いですが、Read theDocsの人々と協力して多くの改善に取り組んでいます。

@ danroth27 RsTには非常に多くの票がありましたが、最終的にMDを選択しましたか？ https://docs.microsoft.com/en-us/aspnet/core/の任意のページで[編集]をクリックすると、GitHubにMDソースファイルが表示されます。
では、なぜMDなのか？

ASP.NETCoreとEFCoreのドキュメントにはしばらくRSTとhttp://readthedocs.comを使用していましたが、最近Microsoftがhttp://docs.microsoft.comに独自のドキュメントインフラストラクチャを構築したため、それに合わせます。 マークダウンはreStructuredTextほど成熟したドキュメンテーション言語ではありませんが、より多くの読者に馴染みがあります。 このため、Read theDocsでも両方の形式をサポートしています。

@ danroth27 Microsoftがマークダウンを使用する独自の非オープンソースのドキュメントジェネレータ/エンジンを作成したということですか？ https://docs.microsoft.comの背後にあるものは何ですか？

マイクロソフトがマークダウンを使用する独自の非オープンソースのドキュメントジェネレータ/エンジンを作成したことを意味しますか？

いいえ。https： //docs.microsoft.comの背後にあるドキュメントエンジンはDocFXであり、.NET上に構築されており、完全にオープンソースです。 フォーマットにはマークダウンを使用します。

こんにちは

これを投稿するのは少し遅いかもしれません。

https://docs.microsoft.comのようなドキュメントサイトを作成できるAPI、フレームワーク、またはツールがあるかどうか疑問に思っていますか？ 私は個人的にマイクロソフトのドキュメントがどのように表示されるかが好きです。 @ danroth27は使用されたエンジンであるDocFXについて言及しました。サイト自体がゼロから行われたものなのか、それとも私たちができるテンプレートやパッケージがあるのか​​を知りたいだけです。同じルックアンドフィールを生成するために使用しますか？ まったく同じではありませんが、変更できるものです:)

ありがとう！
ジュードアルキザ。

DocFxについて読むほど、私はそれが好きになります-すぐに試してみるでしょう。

車輪の再発明をせずに、 https：//docs.microsoft.com/のような独自のドキュメントWebサイトを内部で作成するにはどうすればよいですか？ Pythonドキュメントにはホストされたreadthedocsを使用し、c / c ++ドキュメントにはホストされたdoxygenを使用します。

すべてのAPIドキュメントを1つの屋根の下に置くための最良の方法は何ですか？ このスレッドを読むと、多くの人がsphinx / readthedocsを使用しているようですが、.XMLドキュメントをこれらのツールに適した形式にどのように変換していますか？