Sandcastleを使用したビルド中にHTMLドキュメントを自動的に生成します
-
03-07-2019 - |
質問
Visual Studioのビルド手順を介してHTMLドキュメントを自動的に作成するには、どの手順を実行する必要がありますか?すべてのコメントを配置し、comments.xmlファイルを生成し、Sandcastleをインストールしました。ドキュメントを生成するために、ビルド後のステップに何を追加するかを知る必要があります。
解決
この質問が尋ねられてから、いくつかの変更が行われました。 Sandcastleには SandcastleBuilderConsole.exe
は含まれなくなりました。代わりに、単純な古い MSBuild.exe
を使用します。
これをVisual Studioと統合するために、私がやったことは次のとおりです。
これをビルド後イベントに配置します:
IF "$(ConfigurationName)"=="Release" Goto Exit
"$(SystemRoot)\microsoft.net\framework64\v4.0.30319\msbuild.exe" /p:CleanIntermediates=True /p:Configuration=Release "$(SolutionDir)ProjectName\doc\DocumentationProjectName.shfbproj"
:Exit
これにより、" Release"でビルドした場合にのみ、Visual Studioがドキュメントをビルドします。モード。そうすれば、「デバッグ」でビルドするときに永遠に待つことはありません。開発中のモード。
いくつかのメモ:
-
私のシステムは64ビットですが、あなたのシステムが
msbuild.exe
へのパスでframework64
をframework
に置き換えない場合。 -
設定方法は、ソリューションの各プロジェクトを個別に文書化することです。 「サンドキャッスルヘルプファイルビルダー」をお持ちの場合複数のプロジェクトを一緒に含むプロジェクトファイルを作成する場合は、おそらく
ProjectName \
を削除して、doc
をソリューションディレクトリに移動します。この場合、ソリューションの最後にビルドされたプロジェクトにのみ、ビルド後のイベントコマンドを配置します。すべてのプロジェクトのビルド後イベントに配置すると、ビルドされるプロジェクトごとにドキュメントが再構築されます。言うまでもなく、あなたはしばらくそこに座っているでしょう。個人的には、各プロジェクトを個別に文書化することを好みますが、それは私だけです。
Sandcastleおよび" Sandcastle Help File Builder"のインストール。
Sandcastleと「Sandcastle Help File Builder」の入手方法がわからない場合正しくセットアップしてから、次の手順を実行します。
-
http://sandcastle.codeplex.com/ からSandcastleをダウンロードしてインストールします( 64ビットシステムの場合、環境変数を追加する必要があります。手順はこちら。
-
「Sandcastle Help File Builder」をダウンロードしてインストールします http://shfb.codeplex.com/ から(もしあればMSHelp2に関する警告を無視します。必要になります。)
-
これらをインストールしたら、「Sandcastle Help File Builder」を使用します。新しいドキュメントプロジェクトを作成します。ファイルの保存場所を尋ねられたら、ソリューション/プロジェクトのドキュメントフォルダーに保存します。 http://www.chevtek.com/Temp/NewProject.jpg
-
新しいプロジェクトを作成した後、作成するドキュメントの種類を選択する必要があります。コンパイルされたWindowsヘルプファイル、Webサイト、またはその両方。 http://www.chevtek.com/Temp/DocumentationType.jpg
-
ドキュメントを生成するディレクトリにSHFBプロジェクトファイルを保存した場合は、この手順をスキップできます。ただし、生成されたドキュメントを別の場所に配置する場合は、出力パスを調整する必要があります。 http://www.chevtek.com/Temp/OutputPath.jpg 注:出力パスについて心に留めておくべきことの1つ(1時間イライラしました)は、目的のドキュメントの種類としてWebサイトをチェックすると、出力パスのコンテンツが上書きされることです。彼らがあなたに伝えることを怠っているのは、SHFBが特定のフォルダーが出力パスの一部として含まれることを意図的に制限していることです。デスクトップはそのようなフォルダーの1つです。出力パスをデスクトップ上に置くことはできません。デスクトップのサブフォルダーであってもできません。マイドキュメントでもできませんが、マイドキュメントのサブフォルダにすることができます。ドキュメントの作成中にエラーが発生した場合は、変更してみてください
他のヒント
Codeplex からSandcastle Help File Builderをインストールすることをお勧めします。
これはコマンドラインから実行できます。ビルド後イベントから。最も単純なコマンドラインは次のとおりです。
<install-path>\SandcastleBuilderConsole.exe ProjectName.shfb
Sandcastleは非常に遅いため、リリースビルドでのみ実行します。これを行うには、次のようなコマンドでビルド後イベントを作成します。このコマンドは、構成名をバッチファイルに渡します。
CALL "$(ProjectDir)PostBuild.cmd" $(ConfigurationName)
次に、バッチファイル内で、最初の引数が&quot; Release&quot;かどうかをテストできます。その場合は、SandcastleBuilderConsole.exeを実行します。
上記のようにこれを行う簡単な方法は、Sandcastle Help File Builderを使用することです。 コマンドラインからビルドプロセスにいくつかの変更が加えられ、SandcastleBuilderConsole.exeではなくMSbuildを使用してこれらのプロジェクトをビルドできるようになりました。だからあなたがしなければならないことは次のとおりです:
MSbuild.exe ProjectName.shfb
Sandcastleの現在のバージョンには少し欠けていることを認めなければなりません。大規模なプロジェクトの場合は非常に遅く、統合は容易ではありません(まだ早いため)。
通常の使用では、dllファイルとxmlファイルがあるフォルダーをリフレクターに向けるだけで簡単です。IIRCでは、移動中にxmlファイルがロードされます。
プラス私はほとんど常にリフレクターを開いています...
[編集]チェック済み、はい-逆アセンブラパネルにXMLコメントが表示されます
これらをインストールします:
NDoc: http://prdownloads.sourceforge.net/ndoc /NDoc-v1.3.1.msi?download
HTMLヘルプワークショップ: http ://www.microsoft.com/downloads/details.aspx?FamilyID = 00535334-c8a6-452f-9aa0-d597d16580cc&amp; displaylang = en
次に、NDocConsole.exeコマンドラインを使用して、MSDNまたはCHM形式のドキュメントを生成します。
@c:\ progra〜1 \ NDoc \ NDocConsole.exe MyCode.dll、MyCode.xml -Documenter = MSDN-CHM
私自身はこのための外部ツールを作成し、ショートカットを提供しましたが、前のポスターで述べたように、ポストビルドイベントに接続してそこに行くことができます。
(PS私は数年前から上記の設定を使用しており、非常に満足しています)