2008-10-17 60 views
19

要通過Visual Studio中的構建步驟自動構建HTML文檔需要採取哪些步驟?我準備好了所有的評論和正在生成的comments.xml文件,並安裝了Sandcastle。我只需要知道要在生成後步驟中添加什麼才能生成文檔。在使用Sandcastle構建期間自動生成html文檔

+0

不知道你的目標建立時間偏離航線,但只是想提一提,沙塔真的不是你想對你的日常積累調試周期,包括東西。 – 2008-10-21 06:59:03

+0

沒有,因爲我在這個答案中提到(http://stackoverflow.com/questions/211693/generate-html-documentation-automatically-during-a-build-with-sandcastle#211710)我有一個文件一個單獨的版本。 – 2008-10-21 08:08:33

回答

31

一些變化,因爲這個問題被問。 Sandcastle不再包含SandcastleBuilderConsole.exe。相反,它使用普通的舊版本MSBuild.exe

要與這裏的Visual Studio集成這是我做過什麼:

將此放在您生成後事件:

IF "$(ConfigurationName)"=="Release" Goto Exit 

"$(SystemRoot)\microsoft.net\framework64\v4.0.30319\msbuild.exe" /p:CleanIntermediates=True /p:Configuration=Release "$(SolutionDir)ProjectName\doc\DocumentationProjectName.shfbproj" 

:Exit 

這將導致Visual Studio來構建你的文檔,只有當你建立在「釋放」模式下。這樣,當您在開發過程中建立「調試」模式時,您不會永遠等待。

一對夫婦的注意事項:

  • 我的系統是64位的,如果你沒有再與framework在路徑替換framework64msbuild.exe

  • 我設置它的方式是分別在我的解決方案中記錄每個項目。如果您有一個包含多個項目的「Sandcastle Help File Builder」項目文件,那麼您可能希望擺脫ProjectName\並將doc移動到解決方案目錄中。在這種情況下,您只需要將Post-build事件命令放在您的解決方案中最後構建的項目上。如果您將其置於每個項目的Post-build事件中,那麼您將爲每個構建的項目重建文檔。不用說,你會坐在那裏一段時間。我個人更喜歡單獨記錄每個項目,但那只是我自己。

安裝Sandcastle和「Sandcastle Help File Builder」。

如果你不知道如何讓沙堡和「沙堡幫助文件生成器」設置正確,然後按照下列步驟操作:

  1. 下載和安裝http://sandcastle.codeplex.com/沙堡(如果你有一個64位系統,你將需要添加的環境變量。該指令是here

  2. 下載,如果你得到任何來自http://shfb.codeplex.com/安裝「沙堡幫助文件生成器」(忽略警告有關MSHelp2,你會不會需要它。 )

  3. 安裝完成後,使用「Sandcastle Help File Builder」創建一個新的文檔項目。當它詢問您保存文件的位置時,請將其保存在解決方案/項目中的文檔文件夾中。 http://www.chevtek.com/Temp/NewProject.jpg

  4. 創建新項目後,您需要選擇要創建的文檔類型。編譯的Windows幫助文件,網站或兩者。 http://www.chevtek.com/Temp/DocumentationType.jpg

  5. 如果您將SHFB項目文件保存在要生成文檔的目錄中,則可以跳過此步驟。但是,如果您想將生成的文檔放在其他地方,則需要調整輸出路徑。 http://www.chevtek.com/Temp/OutputPath.jpg 注意:關於輸出路徑(讓我沮喪了一個小時)的一件事是,當您將網站檢查爲所需文檔類型時,它將覆蓋其輸出路徑中的內容。他們忽視的是,SHFB故意限制某些文件夾不屬於輸出路徑的一部分。桌面就是這樣一個文件夾。您的輸出路徑不能位於桌面上,甚至不能位於桌面的子文件夾中。它不能通過我的文檔,但它可以是我的文檔的子文件夾。如果在構建文檔時出現錯誤,請嘗試更改輸出路徑並查看是否修復了它。有關詳細信息,請參閱http://shfb.codeplex.com/discussions/226668?ProjectName=shfb

  6. 最後,您將需要添加對您要記錄的項目的引用。如果您像我一樣在執行單個項目,那麼對於您創建的每個SHFB項目文件,都將引用相應的.CSPROJ文件。如果您的整個解決方案都有一個SHFB項目,那麼您可以找到解決方案的.SLN文件。 (如果你引用編譯後的DLL,sandcastle也可以工作,但是由於你將它與Visual Studio集成在一起,我發現引用項目/解決方案文件更有意義,這也許意味着你選擇哪個項目並不重要做生成後事件上,因爲它的引用代碼,而不是DLL的,但最好是安全的,並把它放在它內建的最後一個項目) http://www.chevtek.com/Temp/AddSource.jpg

  7. 保存項目,你可以關閉「沙堡幫助文件生成器「。現在全部設置完成。只要確保將文檔項目文件放在批處理命令指向Post-build事件的相應文件夾中即可。

我希望我的短教程能幫助你!我很難找到任何體面的教程向我展示如何使用沙堡,更不用說如何將它與視覺工作室集成。希望未來的谷歌搜索會出現這個問題。

6

我建議您從Codeplex安裝Sandcastle Help File Builder。

您可以從命令行運行該命令,例如,來自構建後事件。最簡單的命令行是:

<install-path>\SandcastleBuilderConsole.exe ProjectName.shfb 

沙堡是非常緩慢的,所以我只運行它的發佈版本。要做到這一點,創建一個命令類似於下面的東西,它通過配置名稱到一個批處理文件生成後事件:

CALL "$(ProjectDir)PostBuild.cmd" $(ConfigurationName) 

然後裏面的批處理文件可以測試,如果第一個參數是「發行「如果是這樣的話,運行SandcastleBuilderConsole.exe。

+0

我在後構建腳本中已經這樣做了,我只是檢查配置名稱以確保它是「文檔」(我有3個配置,調試,發佈和文檔)。 – 2008-10-17 11:03:33

+0

更好。意味着您可以在不使用文檔的情況下快速創建發佈版本。 – Joe 2008-10-17 11:06:27

0

我必須承認,我發現目前的Sandcastle版本有點欠缺;對於大型項目來說,它非常緩慢,並且整合起來並不容易(因爲它還很早)。

經常使用,其實我覺得它更容易只是在與DLL和XML文件的文件夾指向反射 - IIRC,它將加載XML文件(S)爲您導航周圍。

另外,我幾乎總是有反射器打開無論如何...

[編輯]檢查,是 - XML註釋顯示在反彙編面板

0

安裝這些:

NDoc的:http://prdownloads.sourceforge.net/ndoc/NDoc-v1.3.1.msi?download

HTML Help Workshop:http://www.microsoft.com/downloads/details.aspx?FamilyID=00535334-c8a6-452f-9aa0-d597d16580cc&displaylang=en

然後使用NDocConsole.exe命令行來生成在任一或MSDN CHM形式文檔:

@c:\ PROGRA〜1個\ NDoc的\ NDocConsole.exe MyCode.dll,MyCode.xml -Documenter = MSDN-CHM

我自己做了一個外部工具用於這一點,並給了它一個快捷方式,但由於以前的海報說,你可以把它掛到一個postbuild事件,你去那裏。

(PS我一直在使用上面設置了好幾年了,我非常喜歡它)

1

一個簡單的方法來做到這一點上面建議使用沙堡幫助文件生成器。 已經有命令行構建過程做了一些改變,現在這些項目可以用的MSBuild而不是SandcastleBuilderConsole.exe建成。因此,所有你需要做的是:已經做出

MSbuild.exe ProjectName.shfb

相關問題