2017年8月8日 星期二

[C#] XML document using Sandcastle


  • 因為 WEB API 可以直接產生 XML Document,產生網頁的 Help page:
  •  如果需要提供"文件檔案"給客戶,開發人員又需要在撰寫文件,網路上有推薦些工具可自動產生文件,幫助開發人員減少需在撰寫文件,可透過程式去維護文件,如下
    • Doxygen
      • C / C++ 開發時有使用此方式編輯,C#使用此軟體一樣可以產生文件檔
    • Sandcastle
      • 此推薦此方法,所產生出來的檔案為 "編譯的 HTML 說明檔案 (.chm)",如有使用到微軟的函式會有超連結,可直接導頁至官方文件
  • Sandcastle
    • 目前新版本為 Help File Builder and Tools v2017.5.15.0
      • drops support for Visual Studio 2013
    • 因此需要使用 Help File Builder and Tools v2017.1.28.0
      • supports Visual Studio 2013
    • 需安裝 SandcastleHelpFileBuilder.msi
    • 執行 SHFBVisualStudioPackage_VS2013.vsix
    • 如執行 SHFBVisualStudioPackage_VS2013.vsix 發生 
    • 需下列步驟 
      • Developer Command Prompt for VS2013" tool in Start >>> Microsoft Visual Studio 2013 >>> Visual Studio Tools
      • 輸入 VSIXInstaller <path to vsix file>
    • 專案可新增 Sandcastle
    • 加入所需要編輯文件的 project
    • Sandcastle 需要兩樣資訊 dll 與 xml,且名稱相同與相同目錄下,如沒有此兩檔案資訊將會無法產生
    • 因輸出設定已經提供給 Help page 
    • 使用 "建置後事件命令列",覆製檔案並更名
    • 此時可以開始建置,但 Sandcastle 依然有出錯訊息

    • 至 Documentation\Help 中查看 LastBuild.log
      • MRefBuilder : error : Unresolved assembly reference: Newtonsoft.Json
      • 網路上提供兩種解法:Unresolved assembly reference with sandcastle
      • 此使用的方法為呼略 Newtonsoft.Json
        • Ignore unresolved references
        • In Documentation (or SHFB) Project Properties / Plug-Ins :
        • Add "Assembly Binding Redirection" in "Plugs-Ins in This Project"
        • configure it to "ignore if Unresolved" "Newtonsoft.Json"
    • 成功產生檔案,但可看到除了 API 的資訊外,還產生許多相關的檔案,需要在整理

沒有留言:

張貼留言