文檔API生成神器SandCastle使用心得

1、功能描述

　　關於Sandcastle網上的參考資料相對較少，Google出來不少資料都是全英文的，相對於我這種英語渣渣看起來仍是很費勁的。

　　言簡意賅，Sandcastle主要功能是可以將C#類生成相似MSDN風格幫助文檔的工具，支持本地化，並提供一個基本的命令行編譯器界面和一個Visual Studio插件。
優勢：

　　1.生成簡單，工做量小，幾分鐘以內就能完成一個項目的api文檔製做。
　　2.自動生成索引項、內容項目表、主題塊和頁面佈局，提升一致性和熟悉程度。
　　3.代碼高亮，易讀性強
　　4.生成api界面美觀。
缺點：

　　只支持visual studio,意思是隻支持微軟旗下產品。

2、下載與安裝

　　我是在github中下載的sandcastle，連接隧道 https://github.com/EWSoftware/SHFB/releases，下載時需注意版本號，我沒有看版本備註就直接下載了最新版本的sandcastle，安裝後生成api後直接報錯了，不能生成成功。後來排查後發現是版本問題，個人idea是vs2013,當前sandcastle版本只支持最低vs2015的Idea,因此一直報錯。

這個版本中備註描述的很清楚，這是最後一個支持vs2013的版本。

3、配置SandCastle

　　主要配置詳解

3.1 首先打開SandCastle，新建一個文件用來存放sandcastle新建的工程文件，相似vs中新建項目後的解決方案。

3.2 在項目屬性中選擇須要生成的api類型，若是你想生成相似MSDN幫助文檔風格，就能夠選擇Website。

3.3 Framework version 選擇生成解決方案的framework版本號，若是與之不一致，則生成api時會報錯

　　chm類型生成的文檔（參考）

　　 website類型

　　在vs中的引用類按f1可打開該類的幫助文檔。

3.4.點擊Project Explorer，點擊新建的api文件，右擊Documentation Sources選擇Add Document Source

　　

3.5 選擇的類庫生成屬性中需在輸出中xml文檔文件複選框打鉤在生成，不然生成api無效。

3.6 選擇所需生成的類庫，也就是後綴名爲.csproj的文件便可

4、常見錯誤

4.1 SHFB: Error BE0043: Unexpected error detected in last build step.  See output above for details.

　　錯誤信息的意思是缺乏程序集的引用，那我就須要把不用的程序集剔除掉，那麼如何剔除呢，請看一下操做

　　

　　

4.2 SHFB: Error BE0064: BUILD CANCELLED BY USER

　　這個錯誤是因爲框架版本不一致所引發的，也就是若是該項目生成時選擇的framework版本爲4.5，而sandcastle配置的是4.0版本，那麼就會報錯。

4.3 Sandcastle [丟失<summary> 節點]的問題

　　遇到這個問題，首先查看代碼註釋是否有<summary>節點，是否規範。

　　

　　而後有人會說我明明在代碼中已經定義了summary 節點，爲何還會報這種錯呢？

　　這種我嘗試最暴力的方法就是讓它不提示這個錯誤，在sandcastle中設置missing tags，取消<summary> elments 的報錯信息，點擊取消複選框，哪一個節點的報錯就不會報錯。

　　

5、SandCastle在vs中的使用

　　前面說了都是sandcastle軟件的獨立使用，還有一種方法是將其集成在vs中使用，使用方法與獨立使用相差不大。

       若是是已經安裝了sandcastle，那麼請忽略如下安裝步驟。

       5.1 在sandcastle目錄文件夾下找到後綴爲vsix的插件，雙擊執行，若是彈出此擴展已安裝，那麼表示安裝成功

　　

5.2 在需生成api的項目下添加項目，若是已安裝成功，那麼在已安裝的擴展插件中Documentation就會出現sandcastle插件，輸入名稱，存放位置，點擊肯定添加。

　　

　　5.3.添加完成後，此時的操做和不是集成在vs中的無明顯差異，如需生成文檔，右擊新建的文件，點擊生成便可。

　　

6、運行生成API

　　上面全部步驟完成以後就能夠運行sandcastle了，點擊build the help file生成

　　

　　生成成功以後在當前生成目錄下，查看生成文件是否齊全，若是文件不全，那麼緣由在於生成不成功或配置不正確

　　

　　雙擊index.html查看api中是否有報錯信息，代碼是否高亮，連接是否可點。