サンドキャッスルとSHFB

これは、サンドキャッスルとSHFBでの作業に関する記事であるため、自分自身を忘れずに他の人に伝えてください。



Sandcastleの前回の記事（ 「.NETでのドキュメントの作成」 ）から4年が経過したため、このドキュメントユーティリティのいくつかのポイントを更新するときが来ました。



私たちのプロジェクトのドキュメントについて疑問が生じたとき、選択は主にDoxygen（プロジェクトで既に使用されていた）とSandcastle（以前に顧客が使用した）の間でした。 その結果、選択はサンドキャッスルに落ちました。 顧客自身が推奨し、Doxygenとは異なり、同様の視覚的なドキュメントを生成し、ヘルプとマニュアルとの統合を行いました（最終的には統合は使用されませんでした）。



グーグルには遅すぎるが、ドキュメント用の他のツールのリストを見るのが面白い人のために、ここに良いリストがあります： stackoverflow.com/a/14420174



簡略化された形式では、タスクは ".chm"ファイルの形式でドキュメントを生成し、サイトでヘルプすることでした。 例として、いくつかのドキュメント化されたクラスとSandcastleプロジェクト自体を含むライブラリの小さなプロジェクトがあります（githubへのリンク： github.com/misiam/Sandcastle-Sample ）。

設置

まず、Sandcastleをインストールするか、Sandcastle Help File Builder（SHFB）をインストールする必要があります。 これは、M $によって悪質に放棄され、Eric Woodruffによって慎重に分岐されたプロジェクトの続きです。 ここからダウンロード： shfb.codeplex.com/releases/view/121365



まず第一に、VS2012とVS2013のchmコンパイラとプラグインは私にとって重要でした。 さらに、Sandcastle Help File Builder自体もインストールされます。これは、xmlファイルにすべてを登録するのではなく、インターフェースを使用できるようにするアプリケーションです。 テキスト編集ツールバー（太字、斜体など）を除いて、SHFBとスタジオ用プラグインの間に違いは見つかりませんでした。また、スタジオはインテリジェンスを備えたオートコンプリートも提供しているため、徐々に開発をそれに移しました。

プロジェクトのセットアップ

すべてが設定されたら、プロジェクトをソリューションに追加できます。 「ドキュメント/サンドキャッスルヘルプファイルビルダープロジェクト」がスタジオでテンプレートに表示され、それを選択して「ドキュメントソース」（ドキュメント化するプロジェクトへのリンク）を追加し、「XMLドキュメントファイル」をプロジェクトに含め、ビルドを実行します。 / binフォルダーに移動しますが、何も見つかりません。 デフォルトでは、Sandcastleはプロジェクトフォルダーの\ Helpフォルダーにファイルを作成します。



これを回避するには、プロジェクトのプロパティ->パス->「ヘルプコンテンツの出力パス」に移動し、たとえば「bin \ Help \」など、より身近なものに変更します。 ビルド後、LastBuild.log（デフォルトでは出力フォルダーに作成されます）およびchmファイルを確認できます。 外観と警告にまだ注意を払ってはいけません。



これで、ヘルプは目的のフォルダーに作成されますが、ヘルプはウェブカメラからも開く必要があり、chmはエクスプローラーのみを完全にサポートしますが、他のブラウザーは対応するプラグインでこのようなヘルプを開くことができます。 ウェブサイトを生成する方が簡単です：プロジェクトのプロパティ->ビルド->「ウェブサイト（HTML / ASP.NET）」をオンにします（実際、そこにもphpがあります。ポストビルドイベントで削除できます。スタジオとSHFBからビルドするときに動作します-msbuildを使用してビルドします）。



Webサイトを追加するとすぐに、次の問題を見つけることができます。1つのフォルダーに両方のヘルプが表示されます。 最愛の人、不快な人、不快な人ではありません。 プロジェクトのプロパティ->プラグイン->出力の展開->追加に移動します。 ここでは、コピーの相対パスを示します。





プロジェクトを整理するために残っているものはほとんどありません。



Website / htmlディレクトリでは、すべてのファイルの形式は[GUID] .htmです。 これを修正するには、プロジェクトのプロパティ->ヘルプファイルに移動し、「トピックファイルの命名方法」プロパティを「GUID」からより読みやすい「メンバー名」に変更します。 これで、ブラウザ行のアドレスは、ユーザーがいるページを反映します。



ドキュメントがない場所では、赤い警告サイン「...にドキュメントがありません」がヘルプに表示されます。







このような碑文は開発には便利ですが、完成した文書では完全に受け入れられません。 それらを削除するには、プロジェクトのプロパティ->欠落しているタグに移動し、ドキュメントがない場合にメッセージを表示しない要素を選択します。 現在使用されている言語は、C＃、VB、C ++、F＃です。 [プロジェクトプロパティ]-> [ヘルプファイル]-> [構文フィルター]をクリックし、必要な言語のみを選択します。

いくつかのページを作成しましょう

まず、プロジェクトからすべてのコンテンツとWelcome.amlページを含むバージョン履歴フォルダーを削除します。 ドキュメントの構造はContentLayout.contentファイルに正確に構築されているため、このファイルを削除する必要があります。



ほとんどの場合、新しいドキュメントページを作成するときは、「概念」タイプを選択する必要があります（多くのタイプがあり、長い間それらについて話すことができます）。 新しいページを作成するときは、ContentLayoutに追加する必要があります。 生成されたコードおよび互いに対して静的ページを構成する可能性は非常に大きいため、必要に応じてトピックツリーを作成できます。



ドキュメントページは、トピックIDを使用して相互にリンクします。 対応する属性のページ上部にあります。



例：

<link xlink:href="b2ac2359-2794-4644-b900-297937ffeaae" />
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

生成されたページにリンクする必要があるときに問題が始まります。 この場合、Sandcastleは<see />メタタグで使用される構文に同意せず、独自の構文を使用します。

 <codeEntityReference qualifyHint="true">M:SandcastleSample.Samples.ConstructorsSamples.#ctor(System.String,System.Int32)</codeEntityReference> <codeEntityReference qualifyHint="true">M:SandcastleSample.Samples.MethodsSamples.MethodWithRefParameter(System.String,System.String@)</codeEntityReference>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

メソッドのシグネチャを表示する場合、 qualifyHintは trueに設定されます。





リストは長く、あなたはそのようなことを知る必要があるだけで、何もする必要はありません。

「ドキュメントがありません...」という警告をオンにすると、Sandcastleがメソッドの名前をどのような形で期待しているかを確認できます。

ヒントとコツ

• さまざまなインターフェイステンプレートがあります：vs2013、vs2010、vs2005、Hana、Prototype。 少なくともvs2013とvs2010を試してみる価値があります。どちらも非推奨ではなく、動作は異なります。 たとえば、vs2013では、検索後、トピックが新しいタブで開きます。これはプロジェクトで重要でした。 また、WebhelpはIndex.aspxとindex.htmlの両方で参照できることに注意してください。 2番目のケースの機能の一部は使用できません（検索など）。
• 名前空間に説明を追加するには、このクラスをそれに含めます。
  
  

   ///<summary>Namespace summary</summary> ///<include file='_Namespace.xml' path='Documentation/*' /> internal class NamespaceDoc { //EMPTY }
        
        
  
          
          
          
        
  
      
          
          
          
        
        
  
          
          
          
        
  
      
       

  
  
  サンドキャッスルでも同じことができます。
  
  
• 生成されたオーバーロードメソッドのトピックに説明を追加するには、次のタグを使用します。
  
  

    /// <summary> /// Go to overload <see cref="O:SandcastleSample.Samples.MethodsSamples.MethodWithOverload"/> /// <example> /// <para>To link to both overloads use 'O': <code>O:SandcastleSample.Samples.MethodsSamples.MethodWithOverload</code></para> /// </example> /// </summary> /// <overloads> /// <para>'overloads' tag used in Sandcastle to put some additional inforation to "Ovetrload methods" page in the documentation.</para> /// </overloads> /// <param name="param"></param> public void MethodWithOverload(string param) { }
        
        
  
          
          
          
        
  
      
          
          
          
        
        
  
          
          
          
        
  
      
       

  
  
  VisualStudioはこのタグを無人のままにしますが、Sandcastleはその内容をドキュメントに追加します。
  
  
  
  このようなタグの表は、 SandcastleのXMLドキュメントコメントにあります。
  
  
  
  もう一度、 githubのサンプルを含むプロジェクトへのリンク。