2016年8月21日 星期日

[.NET] 使用Sandcastle製作軟體help file的sample code

說明:
軟體開發完成後,需要有說明文件方便使用者查詢使用,
微軟有提供CHM(Compiled HTML)的說明檔格式,
使用Sandcastle與GhostDoc(professional版以上)都可產出CHM help file,
但如果還想要加入sample code的頁面,該如何做呢?


作法:
可使用Sandcastle Help File Builder(SHFB)這套免費工具,又是獨立的編譯器,使用上也較方便。

● 先下載SHFB(http://shfb.codeplex.com/)並安裝,安裝後執行Sandcastle Help File Builder GUI。

● 上方選單列->File->New Project->輸入專案名稱並存檔。

● 在右方Project Explorer中的Documentation Sources上右鍵,選擇Add Documentation Sources...,加入軟體專案編譯後的dll與XML,(專案XML需在專案屬性->建置->輸出區塊,勾選XML文件檔案)。

● 接著在專案名稱上右鍵->Add->New Item,加入Code Snippets與Content Layout,可更改檔名後存檔。

● 點開Code Snippets,將item的id改成需要的名稱,例:SampleCode#NewInstance,sampleCode tag中則是要顯示的程式碼,預設有C#與VB,<可用&lt;、>用&gt;取代。

● 點開Content Layout,點選主畫面左上角的Add a new topic as a sibling of the selected topic,選擇Standard Templates的Sample,填入檔名後Add。

● 點開上一步加入的Sample.aml,在section中的content tag中加上<codeReference>item id</codeReference>,例:

<section address="Section1">
      <title>Create Instance</title>
      <content>
        <para>建立實體物件</para>
        <codeReference>SampleCode#NewInstance</codeReference>
      </content>
</section>

● 調整想要的Project Properties後,上方選單列->Documentation->Build Project,建置結束後,選單列->Documentation->View Help File即可。


參考資料:
http://www.codeproject.com/Articles/141766/Creating-documentation-for-a-NET-component-with-Sa
http://community.submain.com/blogs/tutorials/archive/2014/03/05/conceptual-content-adding-custom-content-to-api-documentation-created-with-ghostdoc.aspx
http://huan-lin.blogspot.com/2009/02/use-sandcastle-file-builder-to-create.html
http://www.codeproject.com/KB/XML/csharpcodedocumentation.aspx?msg=1679454