熱點推薦:
您现在的位置: 電腦知識網 >> 編程 >> .NET編程 >> 正文

Sandcastle入門:創建C#幫助文檔

2013-11-13 10:08:33  來源: .NET編程 

  使用Sandcastle
使用平台

  ()操作系統
Windows Server ; Windows XP Service Pack ; Windows Vista;

  ()必備軟件
Microsoft NET Framework Version
HTML Help Workshop——如果需要編譯生成CHM文檔(需要用到其中的hhcexe文件)

  ()可選軟件
Visual Studio
MS Help Compiler from VS SDK

  使用方式(可選界面)Ref[]

  ()使用Sandcastle原始的命令行方式

  ()Sandcastle Help File Builder
它提供一個類似於NDoc的界面允許你輸入現有的NDoc項目自動完成創建過程

  ()SandcastleGUI
這是一個免費的Sandcastle GUI前端界面利用它可以在圖形界面操作省去用戶輸入命令行的麻煩並且具有以下擴充Ref[]
=============================================================================
>>自動在文檔中插入MSDN文章鏈接
>>可以選擇程序集中的某個命名空間生成文檔而不是默認的整個程序集
>>多種輸出方式網站CHM幫助文件或輸出二者
>>自定義幫助文檔頭部(公司LOGO以及產品名稱等)
>>自定義幫助文章頁腳(版權信息等)
>>在文檔中插入自定義的圖像
>>文檔的代碼實例中將C#語法高亮顯示
=============================================================================

  ()Sandcastle CHM編譯BAT腳本和配置實用工具
這是一個配置實用工具和批處理腳本由它通過Sandcastle可建立MSDN形式的類文檔CHM文件

  ()DocProject
DocProject drives the Sandcastle help generation tools using the power of Visual Studio / and MSBuild
生成文檔步驟

  前提代碼文檔中使用規范的///注釋具體規范查看MSDN建議的文檔注釋標記(C#編程指南)也可以參看本人另一篇介紹文章《C#中的XML注釋》

   使用命令行方式

  參考文章Ref[]
——使用sandcastle自帶的例子testcs來生成CHM文件
==========================================================================

  在命令行下打開該文檔所在的路徑例如

  cd \Program Files\Sandcastle\Examples\Sandcastle

  編譯該C#文件並從中抽取///注釋/t參數使得其編譯為dll文件/doc參數使得其同時生成包含///注釋的commentsxml文檔

  csc /t:library /doc:commentsxmltestcs

  運行MrefBuilder生成中間文件

  MRefBuilder testdll /out:

  運行XslTransform將上述中間文件轉換成xml格式(vs)(瑤瑤按使用prototype請參閱Ref[]原文)

  XslTransform /xsl:\\ProductionTransforms\ApplyVSDocModelxsl /xsl:\\ProductionTransforms\AddFriendlyFilenamesxsl /out:reflectionxml

  生成主題清單

  XslTransform /xsl:\\ProductionTransforms\ReflectionToManifestxsl reflectionxml /out:manifestxml

  生成輸出目錄結構(vs

  call \\Presentation\vs\copyOutputbat

  運行BuildAssembler生成HTML主題文件

  BuildAssembler /config:nfig manifestxml

  生成HTML help項目

  XslTransform /xsl:\\ProductionTransforms\ReflectionToChmProjectxsl reflectionxml /out:Output\testhhp

  生成中間表格內容(vs

  XslTransform /xsl:\\ProductionTransforms\createvstocxsl reflectionxml /out:tocxml

  生成HTML help項目信息

  XslTransform /xsl:\\ProductionTransforms\TocToChmContentsxsl tocxml /out:Output\testhhc

  XslTransform /xsl:\\ProductionTransforms\ReflectionToChmIndexxsl reflectionxml /out:Output\testhhk

  運行hhc生成CHM

  hhc output\testhhp

  ==========================================================================

  ==========================================================================
Note:We are providingVS transformsunder Presentation/VS folder and the transforms shipped with the previous versions under Presentation/Prototype folder
For building VS format please nfigfile fromC:\Program Files\Sandcastle\Presentation\vs\Configurationfolder as it uses shared content fromC:\Program Files\Sandcastle\Presentation\vs\Contentand transforms fromC:\Program Files\Sandcastle\Presentation\vs\Transforms
==========================================================================

   Sandcastle Help File Builder
==========================================================================
首先要為項目生成一個包含注釋的XML文件
在c#項目中鼠標右鍵點擊所選的項目選擇Properties>Build項勾選XML documentation file設置完畢編譯項目就可以生成屬於它的xml文件了
打開我們已經安裝好的Sandcastle Help File Builder並對它進行設置
  >>點擊Add按鈕選中項目生成的exedllxml文件
  >>保存該項目後點擊Namespaces按鈕選中想要生成幫助文檔的Namespace
  >>設定Dependencies選項把項目中所引用到的dll文件加載進去
  >>設置HtmlHelpxCompilerPath為HTML Help Workshop的安裝路徑
  >>設置SandcastlePath為Sandcastle的安裝路徑
點擊頂頭菜單Documentation下拉菜單中的Build Project選項

  (或直接使用快捷鍵Ctrl+Shift+B)編譯即可生成所需的幫助文檔
該文檔的默認輸出路徑在項目所在目錄的Help文件夾下當然也可以更改Sandcastle Help File Builder中的設置自己設定它的輸入路徑==========================================================================

   SandcastleGUI

)生成各項目的*dll和*xml文件(在vs中編譯選項設置具體前面 Sandcastle Help File Builder的生成步驟中已提及)
)將*dll和*xml文件放在一個目錄A下將所有要附加的圖片(比如類圖和時序圖)放在另一個並行的目錄B下(注意不能有子文件夾)
)啟動SandcastleGUI設置
Directory that contains assemblies to document項選擇目錄A
Output directory項選擇一個空文件夾如C
Directory to include in documentation項選擇目錄B
其它如C#語法是否包含C#例子生成文檔類型(website或chm)等選項根據需要填
)設置完成後最好Save settings因為可能常常要用到然後Start documenting
)等待生成完成後就可以在C目錄下找到chm文件了

   Sandcastle CHM編譯BAT腳本和配置實用工具
DocProject

  參考文章Ref[]
——使用MSDN上包含有標准注釋的XML文檔生成幫助文件示例
==========================================================================
先編寫一個類庫這裡使用的是MSDN上包含有標准注釋的XML文檔示例
打開下載到的工程文件 打開XMLsamplecs 可以看到各種注釋的詳細解釋

  使用DocProject方式 在確保安裝了DocProject後 為工程添加新項目

  ==>==>==>==>

  編譯DocProject前 務必使你所要生成文檔的類庫編譯輸出注釋的XML文件 詳細方法請查看在Visual Studio中生成XML文檔示例
編譯DocProject項目 等待十幾分鐘(似乎有點慢 即使類庫很小) 就會在該項目下看到HTML版和CHM版的文檔了


From:http://tw.wingwit.com/Article/program/net/201311/12684.html
    推薦文章
    Copyright © 2005-2013 電腦知識網 Computer Knowledge   All rights reserved.