利用SandCastle生成幫助文檔

1、Sandcastle入門：創(chuàng)建C#幫助文檔今天學到了一個東西：利用vs2005生成的dll/xml來生成幫助文檔。完成這個偉大任務的是Sandcastle，微軟推出的類庫文檔編譯工具。在開始這篇筆記之前，我想先感謝我文后提及的七篇關于Sandcastle的文章。是它們出 色的闡述使得我能夠整理出這篇筆記，之前我從未接觸過。對于那七篇文章，我努力尋找它 們的源出處鏈接，然而網(wǎng)絡的傳播性使得這些一再被轉(zhuǎn)載的文章逐漸模糊了它們的來源，有 一些是我無法確定的。因此，我希望，如果這篇文章有幸能被您轉(zhuǎn)載，請注明轉(zhuǎn)載和出處, 謝謝。o（Q_Q）o（瑤瑤按：由于本文較長且從word移植到baidu的諸多不便，

2、本文將分成3個部分分別 發(fā)布）目錄 TOC o 1-5 h z 名詞解釋：Sandcastle1 HYPERLINK l bookmark2 o Current Document Background1Sandcastle Overview1使用 Sandcastle24.1使用平臺4.2使用方式（可選界面）4.3資源下載生成文檔步驟35.0使用命令行方式Sandcastle Help File BuilderSandcastleGUISandcastle CHM編譯BAT腳本和配置實用工具DocProject6. References311名詞解釋:SandcastleDocumentati

3、on compilers for managed class librariesEnabling managed class library developers throughout the world to easily create accurate, informative documentation with a common look and feel.2Backgroundnt在微軟推出Sandcastle之前，人們傾向于選擇開源的NDoc（.NET代碼文檔生成器）。 NDoc可以將nt在微軟推出Sandcastle之前，人們傾向于選擇開源的NDoc（.NET代碼文檔生成器）。

4、NDoc可以將C#.NET編譯生成的程序集和對應的/doc XML文檔，自動轉(zhuǎn)換成如.NET Framework SDK類庫文檔或者MSDN Library在線.NET類庫文檔形式的代碼文檔：J-二E1 “彎韓SHO您 j El-He-Oan命 CLmCluf *； CmlRGkh an CLuMMiMulB鄴 Qhs.*電防咖血-i*UfriTrr.rd Qm弓葉9 k M ；E N it WSH?冷Tfrfi口 w cJ” i - fhkttihI datr.For-fe lilC $1 ill mcmbM.ofwft Claia FnfhgF9ubflr fuii-; i red in

5、YgW Baxrck FFflrabci E/ihd*r* 11 PDpfW,Irsunoi rnKTben 曬 no! guttrrTteEdi in b PirtjrsnkKcmiirki344出3知幣 UZ幣 ilMSt-WII HUU希WiSh ZtHI叭 WRM* 兇齋Ai世rMbl貞W NDU.TM!.J 1他eHp I HD&cTZ F15ejpfl oejhebb f 曲 m .韻rrvfxrm j-j.然而遺憾的是，這個項目由于資金等問題，作者Kevin于2006年7月宣布不再投入NDoc 開源項目的開發(fā)，NDoc停留在1.3的歷史版本，無法完全支持.NET 2.0，將漸漸淡

6、出人們 的視野。在發(fā)布VS2005之前，MS內(nèi)部開發(fā)了一個用于生成幫助文檔的工具。這就是Sandcastle 的前身。但是當時編譯一次文檔就需要十多個鐘頭，這使得這個工具可用性不強。后來發(fā)布 的Sandcastle由于做了很大的優(yōu)化，就只要30分鐘了。當然，現(xiàn)在的Sandcastle經(jīng)歷了幾 個CTP版本的測試已經(jīng)比較成熟了。（Refl,有增刪）（注：CTP, Community Technology Preview）。Sandcastle 目前（2007 年 10 月 30 日）為止最新的版本是 September 2007 CTP， version 2.3.07930.06, 2007年1

7、0月1日發(fā)布。（瑤瑤按：在寫這篇日志的過程中，MS發(fā)布 了新的 Sandcastle 版本 October 2007 CTP，version 2.3.8000.26，2007 年 10 月 29 日發(fā)布。相 應地后面提到的SandcastleGUI也進行了更新。）3.Sandcas tie OverviewSandcastle是一個管理類庫的文檔編譯器，是用于編譯發(fā)布組件（Assembly）信息的一 個工具，這個工具通過反射和Xslt技術，可以從dll文件及其xml注釋（命令行編譯時力加/doc 參數(shù)或vs2005設置項目屬性得到）得到一個完整的幫助文檔，格式可以是Html或CHM甚 至是任何

8、自定義的格式。（Ref2, Ref3，有增刪整合）Sandcastle 與.NET Framework 2.0 和.NET Compact Framework 組合使用。Sandcastle 支持 本地化，并提供一個基本的命令行編譯器界面和一個Visual Studio插件。（Ref2） 4.Sandcastle Process （ Ref2）Sandcastle 中共有三個組件：MrefBuilder、Build Assembler 和 XslTransform。這些工具 使用編譯匯編代碼時生成的輸出結(jié)果，包括DLL文件以及XML注釋文件。MrefBuilder反射一個項目的匯編代碼并生成一

9、個輸出文件。MrefBuilder是一個隨 Sandcastle安裝的命令行工具。它生成的輸出文件通過XslTransform命令行工具轉(zhuǎn)換成一個 叫做reflection.xml的文件。reflection.xml文件包含所有文檔數(shù)據(jù)，但不提供顯示細節(jié)。MrefBuilder完成工作后，立即由Build Assembler接手處理。Build Assembler可由命令 行工具BuildAssembler啟動。它利用由MrefBuilder生成的數(shù)據(jù)（reflection.xml）和任何代碼注 釋（保存在獨立的XML文件中），生成按邏輯分組的HTML文件。HTML Help Compiler

10、 再利用這些HTML文件生成最終結(jié)果。該工具并未限制你一次處理一個匯編。如果你需要處理幾個匯編代碼，你必須深入了解 Sandcastle配置文件。它是一個包含建立幫助文件主題所需步驟的XML文件。反射MreBuilder匯編代碼中間文件HTML Help ComplierHTML最終文檔反射MreBuilder匯編代碼中間文件HTML Help ComplierHTML最終文檔（圖：Sandcastle工作過程）Sandcastle生成的輸出結(jié)果具有以下特點：0 類似于MSDN布局的界面。0自動生成索引項、內(nèi)容項目表、主題塊和頁面布局，提高一致性和熟悉程度。0自動生成語法宣稱部分。0自動生成繼

11、承表。0代碼彩色化。0 提供多種風格和語言選擇，終端用戶可從中選擇自己最喜歡的形式。0輸出結(jié)果以HTML和CSS形式顯示，微軟承諾將來提供更多選擇。OverviewSandcastle produces accurate, MSDN style, comprehensive documentation by reflecting over the source assemblies and optionally integrating XML Documentation Comments. Sandcastle has the following key features:l Works wi

12、th or without authored commentsl Supports Generics and .NET Framework 2.0l Sandcastle has 2 main components (MrefBuilder and Build Assembler)l MrefBuilder generates reflection xml file for Build Assemblerl Build Assembler includes syntax generation, transformation.etcl Sandcastle is used internally

13、to build .Net Framework documentation4使用 Sandcastle41使用平臺（1）操作系統(tǒng)：Windows Server 2003; Windows XP Service Pack 2; Windows Vista;（2）必備軟件：Microsoft .NET Framework Version 2.0HTML Help Workshop如果需要編譯生成CHM文檔（需要用到其中的 hhc.exe 文件）（3）可選軟件：Visual Studio 2005MS Help Compiler from VS SDK4.2使用方式（可選界面）Ref2（0）使用Sa

14、ndcastle原始的命令行方式（1）Sandcastle Help File Builder它提供一個類似于NDoc的界面，允許你輸入現(xiàn)有的NDoc項目，自動完成創(chuàng)建 過程。（2）SandcastleGUI這是一個免費的Sandcastle GUI前端界面。利用它可以在圖形界面操作，省去用 戶輸入命令行的麻煩。并且具有以下擴充Ref6:自動在文檔中插入MSDN文章鏈接可以選擇程序集中的某個命名空間生成文檔，而不是默認的整個程序集 多種輸出方式：網(wǎng)站、CHM幫助文件或輸出二者自定義幫助文檔頭部（公司LOGO以及產(chǎn)品名稱等）自定義幫助文章頁腳（版權信息等）在文檔中插入自定義的圖像文檔的代碼實例中

15、將C#語法高亮顯示Sandcastle CHM編譯BAT腳本和配置實用工具這是一個配置實用工具和批處理腳本，由它通過Sandcastle可建立MSDN形式 的類文檔CHM文件。DocProjectDocProject drives the Sandcastle help generation tools using the power of Visual Studio 2005/2008 and MSBuild.4.3資源下載Sandcastle October 2007 CTP 下載地址：(Update： version 2.3.8000.26, Released Date： 2007-10

16、-29) HYPERLINK /downloads/details.aspx?familyid=E82EA71D-DA89-42EE /downloads/details.aspx?familyid=E82EA71D-DA89-42EE -A715-696E3A4873B2&displaylang=enHTML Help Workshop 下載地址：(version1.4) HYPERLINK /en-us/library/ms669985.aspx /en-us/library/ms669985.aspxSandcastle Help File Builder 下載地址：(Update： v

17、ersion, Released Date： 2007-10-31) HYPERLINK /SHFB/Release/ProjectReleases.aspx?ReleaseId=7543 /SHFB/Release/ProjectReleases.aspx?ReleaseId=7543SandcastleGUI 下載地址：(Update： version1.40. Released Date： 2007-11) HYPERLINK http:/www.inchl.nl/SandcastleGUI/(%e7%91%b6%e7%91%b6%e6%8c%89%ef%bc%9a%e8%bf%99%e

18、4%b8%aa%e9%9c%80%e8%a6%81%e7%99%bb%e8%ae%b0%e9%82%ae%e7%ae%b1%ef%bc%8c%e5%86%8d%e4%bb%8e%e9%82%ae%e7%ae%b1%e8%8e%b7%e5%8f%96 http:/www.inchl.nl/SandcastleGUI/(瑤瑤按：這個需要登記郵箱，再從郵箱獲取 下載鏈接)DocProject 下載地址：(version1.8.0. Released Date： 2007-10-04， Update： version1.9.0 for October 2007 CTP will be availabl

19、e) HYPERLINK /DocProject/Release/ProjectReleases.aspx?ReleaseId=6652 /DocProject/Release/ProjectReleases.aspx?ReleaseId=66525生成文檔步驟前提：代碼文檔中使用規(guī)范的/注釋，具體規(guī)范查看MSDN-建議的文檔注釋標 記(C#編程指南)。也可以參看本人另一篇介紹文章：C#中的XML注釋 5.0使用命令行方式參考文章：Ref7使用sandcastle自帶的例子test.cs來生成CHM文件1在命令行下打開該文檔所在的路徑。例如：cd Program FilesSandcastle

20、ExamplesSandcastle 2編譯該C#文件，并從中抽取/注釋：/t參數(shù)使得其編譯為dll文件，/doc參數(shù)使得其同時生成 包含/注釋的comments.xml文檔。esc /t:library /doc: comments.xml test.cs運行 MrefBuilder 生成中間文件 MRefBuilder test.dll /out: 運行XslTransform將上述中間文件轉(zhuǎn)換成xml格式（vs2005）（瑤瑤按：使用prototype請參 閱Ref原文）XslTransform /xsl:.ProductionTransformsApplyVSDocModel.xsl

21、/xsl: .ProductionTransformsAddFriendlyFilenamesxsl /out: reflection.xml5生成主題清單XslTransform /xsl：ProduetionTransformsRef1ectionToManifestxsl reflection.xml/out:manifest.xml6生成輸出目錄結(jié)構(gòu)（vs2005）call .Presentationvs20O5copyOutput.bat7運仃BuildAssembler生成HTML主題文件BuildAssembler /config:sandcastle.config manife

22、st.xml&生成HTML help項目XslTransform /xsljIAProductionTransformsWeflectionToChmProject.xsl reflection.xml /out:Outputtest.hhp生成中間表格內(nèi)容（vs2005）XslTransform /xsljIAProductionTransformscreatevstoc.xsl reflection.xml /out: toc.xml生成HTML help項目信息XslTransform /xsljlAProductionTransformsTocToChmContents.xsl toc

23、.xml /out:Outputtest.hhcXslTransform /xsl:.ProductionTransformsReflectionToChmIndex.xsl reflection.xml /out:Outputtest.hhk11.運行hhc生成CHMhhc outputtest.hhpNote:7. We are providing VS 2005 transformunder Presentation/VS2005 folder and the transforms shipped with the previous versions under Presentation

24、/Prototype folder.For building VS2005 format please use sandcastle.config file from C:Program FilesSandcastlePresentationvs2005Configuration folder as it uses shared content from C:Program FilesSandcastlePresentationvs2005Content and transforms from C:ProgramFilesSandcastlePresentationvs2005Transfor

25、ms5.1 Sandcastle Help File Builder參考文章：Ref5首先要為項目生成一個包含注釋的XML文件在c#項目中鼠標右鍵點擊所選的項目，選擇Properties-Build項，勾選XML documentation file。設置完畢編譯項目，就可以生成屬于它的xml文件了。打開我們已經(jīng)安裝好的Sandcastle Help File Builder并對它進行設置點擊Add按鈕，選中項目生成的exe,dll,xml文件保存該項目后點擊Namespaces按鈕，選中想要生成幫助文檔的Namespace設定Dependencies選項，把項目中所引用到的dll文件加載進去

26、 設置 HtmlHelp1xCompilerPath 為 HTML Help Workshop 的安裝路徑， 設置 SandcastlePath 為 Sandcastle 的安裝路徑點擊頂頭菜單Documentation下拉菜單中的Build Project選項（或直接使用快 捷鍵Ctrl+Shift+B）編譯即可生成所需的幫助文檔4該文檔的默認輸出路徑在項目所在目錄的Help文件夾下，當然也可以更改 Sandcastle Help File Builder中的設置，自己設定它的輸入路徑。Sandcas tleGUI以下圖片參考文章：Ref6（按：新版本的界面有差異，但大體相同。） 界面：rZ

27、l氏 TctI Micresgfl vkyjl O WEII- &ESJ1上9fiwt-; ih-nr trd in VihmirZl氏 TctI Micresgfl vkySri岔IrvLfenoo msnberii ire noE Qutputeed 1 口 be treadrMart3a*靳*曲卜審Iwmjff.W * 曠呻鼻* *:Pt.笑* Xeg 哄1 dvtcK 9 Ggdtafte iSdmw 為d0 PDdrf.TrI*tefirwhwcrarOSl Sfihwt-宅I皿 IMSJg 孫E*;電冷siFdaua聊如t電亦tdzanBwef lihMI硏 EfiUk冶rr.rd

28、jalEenutrflflOf- 曉do由*i 1 _s*W.ET*wrr|rrwn 廠EM:PtLMiDf；AIMIPISiZc-iD旦M .VT 鼻 n 申誑EEJJ.呂V 腳?C匙業(yè)仲智劭TWirf 匸1怖$齊Clis弘曜 rR.npcf4rn znrml dis-s.Per 百 l唉 白 ill nwmben. of(vm&ClBlii HerriMHDnirtdlifF1 j iwa n;tanra nl !Itp I-kjiifc *l3Er.缸比應皆叫AH a出sCwtauMCDWlcinirtdlifF1 j iwa n;tanra nl !Itp I-kjiifc *l3Er

29、.缸比應皆叫|PHflmnK RfxcaEK-rr-dfcHliiAC i*祜曲 JKRQEgifm也曲1曲 femvig, lAasinq. or rfnron iwrruriaMl r-Hxrip g jpe：ified Grapfilcs -abjecE.*4ft|H-ali(dhjE-LE)畫割】猛:爲X曙器Online MSDN links filloWF ?n n-hjct 恂to *4 呻1TC電乍 *MI iwr。 4t刪 Comrup cpsr/KoE 知片石”可 E劃V nfrdAmqe bycartyae colcctm.Irhurtrf rrciTi UtJlucl.)

30、Sr II9avIIiCu*n*nU #4ASrucEunfia Hcd ji hjdh CJbla.tTyprtUGcf-E Hit Ivr 卄 tfQ DJF*nt rKtjnco-. Inhwrted bom OtlocL)O日4怔h 9 ihjiGH qwythe cwncrt *Ob|iect-帛pen Ohjncl.7a5lrir0RahJiDS a Strni ttvit何nls th呂 owTSfii： Ob4ctIrhentiJ Hwn OlijiKl.)(? IntjnciiP =5也衣P orbrad 戸 Inhnt94P GteHT-卜XKmpj。五The foldHi

31、fig exampie 3ha9 h& 4 circle can bt CGfdQrjcucL:-丄asa Clz-ulcC# ynLix fuimatted cod已 exdiiiple (colors and code-Fulding)13puhlle o*3!iri- watJ l-zitMlS/PTtnRDrt-viiif Csm 論 kne yjSiTS-et.匚XHr.ung.jez pe- 3ev Syjzcs.Ii!A.i!ur-tDuvjjjs-匚 gzdpDicdLEiiiv丄丄丄匚e=CFiww a Bdd EfiqglrK1ApplicationPiOjetfDocum

32、entatio n削 FtapartJM -弓騰Cv*5cImi .DkPtci 根職:=CFiww a Bdd EfiqglrK1ApplicationPiOjetfDocumentatio n削 FtapartJM -弓騰Cv*5cImi .DkPtci 5ystniJHLdn:=tErili rtlJI Ml h “ ikaHi HW ir姑T*ah if.W In=ChooKt Cwnplled Hilp斗 l4-| LG 屮r 上.MJ G4P U衛(wèi)，申邙 b i .11 啼 ThA 1ti!nh ?I F,1 |W?SSV-hirifl ta bn km： rluMi da* 昨7

33、右血3.使用DocProject方式，在確保安裝了 DocProject后，為工程添加新項目;J ft 神 Lj UxmPmentatw i _J 軸& 1二酬.t QfivJ.：t _j rraftstwrtsfl BiridProcrs$. cs14編譯DocProject 前,務必使你所要生成文檔的類庫編譯 輸出注釋的XML文件，詳細方法請查看在Visual Studio中生成“XML文檔”示例 5編譯DocProject項目，等待十幾分鐘（似乎有點慢，即使類庫很小），就會在該項 目下看到HTML版和CHM版的文檔了。6.ReferencesRef1： Sandcastle： NDoc 的繼承人By Lex Mark （李楊），2006-11-12 HYPERLINK /TrackBack.aspx?PostId=1380172 /TrackBack.aspx?PostId=1380172Ref2：用微軟Sandcastle創(chuàng)建.NET文檔, 2007-04