クラスドキュメントの提案

Question

当社は C# の使用に重点を置いた Microsoft ショップです。Web サイト、Windows サービス、クラス ライブラリなど、XML コメントを組み込んだプロジェクトがいくつかあります。

プロジェクトごとに MSDN スタイルの HTML ドキュメントを生成し、すべての開発者が簡単にアクセスできる一元的な場所に展開したいと考えています。また、これらのステップを自動化して定期的に実行できるようにしたいと考えています。そうすることで、私や他の開発者は、変更が行われるたびに新しいドキュメントを生成して展開することを忘れずに済むようになります。Sandcastle と Doxygen を検討しましたが、どちらも必要なドキュメントを生成するための優れたオプションのように見えますが、夜間のジョブなどでドキュメントの生成を自動化する良い方法についてアドバイスが必要です。

このようなことをしている人はいますか？私は最終結果が HTML になるとは思っていません。特により良いアイデアがある場合は。

編集：

良いアイデアすべてに感謝します。現在調査できるルートはいくつかありますが、実際に手を動かしてみるまではどれが最適かわかりません。Sandcastle Help File Builder は、私がやりたいことに対して最適なオプションを提供してくれるようなので、その提案に同意します。ただし、XML データを正しく表示するために XSLT および CSS ソリューションに取り組む時間がもっとあれば、私はまずその提案を追求するでしょう。

みなさん、改めてありがとう！

Answer 1

を見てみましょう Sandcastle ヘルプ ファイル ビルダー. 。これはスタンドアロン プロジェクトを使用するため、好きなだけビルドできます (たとえば、毎晩、またはプロジェクトの一部として) 継続的インテグレーション 変更がチェックインされるたびにシステムに反映されます)。

Answer 2

優れたドキュメントを生成するためにサードパーティのツールは必要ありません。C＃コンパイラはXMLのXMLコムメントからドキュメントを出力できます。必要なのは、ブラウザでそれを表示するために素敵なCSSを設計することだけです。満足していない場合は、CSSを適用する前に独自のXSLTトランスフォーメーションを生成することもできます。 ここで説明するように （コメントでCSSの例を探してください！）。

または、このXMLドキュメントを取得して、次のようなものを使用して改善することができます ndoc. 。がここにあります 素敵な記事 それを行う方法について、残念ながらやや時代遅れです。

コンパイラを実行することにより、プロジェクトのドキュメントのみを単一のXMLファイルに手動で構築できます /doc:documentationfilename.xml パラメーター。

また、Visual Studio（Project Properties-> Documentation）でこのオプションをプロジェクトのすべてのビルドに追加して、プロジェクトを構築するたびにXMLファイルを生成することもできます。その後、ビルド後のイベントをフックして、XMLファイルをリポジトリにコピーできます。

また、Team Foundation ServerにMSビルドを設定してドキュメントを作成し、同様の方法でリポジトリにコピーすることもできます（/p:DocumentationFile=fileName.xml);

Answer 3

私は私たちのプロジェクトでそれをします。基本的に、DoxyWizardを使用して、生成されたHTMLの仕様を設定する構成DoxyFileをセットアップします。次に、ビルドサーバーのステップで「Doxygen doxyfile」を呼び出します。

DoxyFileは、Webサーバーから見える領域にDoxygenファイルを生成するように構成されています。そのため、各コミットにトランクにコミットすると、ドキュメントが自動的に再構築されます。