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

Question

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

各プロジェクトのMSDNスタイルのHTMLドキュメントを生成し、すべての開発者が簡単にアクセスできる中央の場所に展開することを検討しています。また、これらのステップを自動化して定期的に実行できるようにして、私と他の開発者は、変更があったときにいつでも新しいドキュメントを生成して配備することを心配する必要はありません。私はSandcastleとDoxygenを見てきましたが、両方とも私が望むドキュメンテーションを生成するための良い選択肢に見えますが、夜間の仕事などのように生成を自動化する良い方法についてアドバイスが必要です。

誰でもこのようなことをしていますか？私は最終結果でHTMLであることを売っていない。特に良い考えがある場合は特にそうです。

編集：

すべての良いアイデアを歓迎します。今私が調査できるルートがいくつかありますが、私が手を汚すまではどちらが一番うまくいくのかわかりません。サンドキャッスルのヘルプファイルビルダーは、自分が探しているものに最適なオプションを提供しているようですので、その提案にうなずきます。しかし、XSLTとCSSソリューションを使ってXMLデータを見た目にする時間があれば、まずその提案を追求したいと思います。

もう一度おねがいします！

Answer 1

Sandcastle Help File Builderをご覧ください。これはスタンドアロンプ​​ロジェクトを使用するため、好きなだけ頻繁にビルドすることができます（たとえば、毎晩、または変更がチェックインされるたびにcontinuous integrationシステムの一部として）。

Answer 2

私はそれをプロジェクトで行っています。基本的には、doxywizardを使ってDoxyfileの設定を設定します。これは、生成されたhtmlの仕様を設定します。次に、ビルドサーバーのステップで、私は "doxygen doxyfile"を呼び出します。

私たちのDoxyfileは、私たちのWebサーバーから見える領域にdoxygenファイルを生成するように設定されています。したがって、トランクにコミットするたびにドキュメントが自動的に再構築されます。

Answer 3

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

また、このXMLドキュメントを利用して、NDocのようなものを使用して改善することもできます。残念ながらそれをやる方法については、nice articleです。

/doc:documentationfilename.xmlパラメータを使用してコンパイラを実行すると、プロジェクトのドキュメントのみを1つのXMLファイルに手動でビルドできます。

Visual Studio（プロジェクトプロパティ - >ドキュメント）でこのオプションをプロジェクトのすべてのビルドに追加することもできます。これにより、プロジェクトをビルドするたびにXMLファイルが生成されます。ビルド後のイベントをフックして、XMLファイルをリポジトリにコピーすることができます。

Team Foundation ServerでMSビルドをセットアップして、ドキュメントをビルドして同様の方法でリポジトリにコピーすることもできます（/p:DocumentationFile=fileName.xml）。