在使用Sandcastle構建期間自動生成html文檔

Question

通過Visual Studio中的構建步驟，我需要采取哪些步驟來自動構建HTML文檔？ 我已經准備好所有注釋並生成了comments.xml文件，並安裝了Sandcastle。 我只需要知道要在構建后步驟中添加什么以生成文檔。

Answer 1

自從提出這個問題以來，已經做了一些改變。 Sandcastle不再包含SandcastleBuilderConsole.exe 。 相反，它使用普通的舊MSBuild.exe 。

我將這個與視覺工作室整合在一起是我做的：

將其放在Post-build活動中：

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位，如果你的系統不是，那么用msbuild.exe路徑中的framework替換framework64 。

• 我設置它的方法是單獨記錄我的解決方案中的每個項目。 如果您有一個“Sandcastle幫助文件生成器”項目文件，其中包含多個項目，那么您可能希望擺脫ProjectName\\並將doc移動到解決方案目錄中。 在這種情況下，您只希望將Post-build事件命令放在解決方案中最后構建的項目中。 如果將它放在每個項目的Post-build事件中，那么您將為每個構建的項目重建文檔。 不用說，你會在那里坐一會兒。 我個人更喜歡單獨記錄每個項目，但那只是我。

安裝Sandcastle和“Sandcastle幫助文件生成器”。

如果您不知道如何正確設置Sandcastle和“Sandcastle幫助文件生成器”，請按照下列步驟操作：

1. 從http://sandcastle.codeplex.com/下載並安裝Sandcastle（如果您有64位系統，則需要添加一個環境變量。說明在這里 。

2. 從http://shfb.codeplex.com/下載並安裝“Sandcastle幫助文件生成器”（如果有任何問題，請忽略有關MSHelp2的警告。您將不需要它。）

3. 安裝完成后，使用“Sandcastle幫助文件生成器”創建新的文檔項目。 當它詢問您保存文件的位置時，請將其保存在解決方案/項目中的文檔文件夾中。 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. 保存項目，您可以關閉“Sandcastle幫助文件生成器”。 現在一切都安裝好了。 只需確保將文檔項目文件放在批處理命令指向Post-build事件的相應文件夾中。

我希望我的簡短教程可以幫助你！ 我很難找到任何體面的教程向我展示如何使用sandcastle，更不用說如何將它與visual studio集成。 希望未來的谷歌搜索會出現這個問題。

Answer 2

我建議您從Codeplex安裝Sandcastle幫助文件生成器。

您可以從命令行運行此命令，例如從Post-Build事件中運行。 最簡單的命令行是：

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

Sandcastle非常慢，所以我只為Release Builds運行它。 為此，使用如下命令創建Post-Build事件，該命令將配置名稱傳遞給批處理文件：

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

然后在批處理文件中，您可以測試第一個參數是否為“Release”，如果是，則運行SandcastleBuilderConsole.exe。

Answer 3

如上所述，一種簡單的方法是使用Sandcastle幫助文件生成器。 從命令行對構建過程進行了一些更改，現在可以使用MSbuild而不是SandcastleBuilderConsole.exe構建這些項目。 所以你要做的就是：

MSbuild.exe ProjectName.shfb

Answer 4

我必須承認，我發現當前版本的Sandcastle有點缺乏; 對於大型項目而言，它很慢，並且不易整合（因為它還處於早期階段）。

對於常規使用，我實際上發現將反射器指向帶有dll和xml文件的文件夾更容易 - IIRC，它將在您導航時加載xml文件。

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

[edit]選中，是 - 在反匯編程序面板中顯示xml注釋

Answer 5

安裝這些：

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

HTML幫助研討會： 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

我自己已經為此制作了一個外部工具，並給了它一個快捷方式，但正如之前的海報所說，你可以把它連接到一個后期建築事件，你就去了。

（PS我已經使用上面的設置幾年了，我很高興）