Некоторые изменения были внесены после того, как был задан этот вопрос. 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 будет создавать вашу документацию, только когда вы работаете в режиме "Release". Таким образом, вы не будете ждать вечно, когда будете строить в режиме «Отладка» во время разработки.
Пара замечаний:
Моя система 64-битная, если у вас ее нет, замените framework64 на framework в пути к msbuild.exe.
Способ, которым я его настроил, состоит в том, чтобы документировать каждый проект в моем решении индивидуально. Если у вас есть файл проекта «Sandcastle Help File Builder», который включает в себя несколько проектов вместе, то вы, вероятно, захотите избавиться от ProjectName\ и переместить doc в каталог решений. В этом случае вы захотите поместить только команды событий Post-build в проект, созданный LAST в вашем решении. Если вы поместите его в событие Post-build для каждого проекта, то вы будете перестраивать свою документацию для каждого создаваемого проекта. Само собой разумеется, вы будете сидеть там некоторое время. Лично я предпочитаю документировать каждый проект индивидуально, но это только я.
Установка Sandcastle и "Построителя файлов справки Sandcastle".
Если вы не знаете, как правильно настроить Sandcastle и «Построитель файлов справки Sandcastle», выполните следующие действия:
Загрузите и установите Sandcastle из http://sandcastle.codeplex.com/ (если у вас 64-битная система, вам нужно добавить переменную окружения. Инструкции здесь .
Загрузите и установите «Построитель файлов справки Sandcastle» из http://shfb.codeplex.com/ (игнорируйте предупреждения о MSHelp2, если они у вас есть. Он вам не понадобится.)
Как только они будут установлены, используйте «Построитель файлов справки Sandcastle», чтобы создать новый проект документации. Когда он спросит вас, где сохранить файл, сохраните его в папке с документацией, имеющейся в вашем решении / проекте.
http://www.chevtek.com/Temp/NewProject.jpg
После создания нового проекта вам нужно выбрать, какую документацию вы хотите создать. Скомпилированный файл справки Windows, веб-сайт или оба.
http://www.chevtek.com/Temp/DocumentationType.jpg
Если вы сохранили файл проекта SHFB в каталоге, где вы хотите, чтобы ваша документация была сгенерирована, то вы можете пропустить этот шаг. Но если вы хотите, чтобы сгенерированная документация была размещена в другом месте, вам нужно настроить выходной путь.
http://www.chevtek.com/Temp/OutputPath.jpg
ПРИМЕЧАНИЕ. Следует помнить одну вещь о пути вывода (что меня расстраивало в течение часа): если у вас выбран веб-сайт в качестве типа документации, который вы хотите, он перезапишет содержимое в своем пути вывода. Чего они не хотят вам сказать, так это того, что SHFB преднамеренно ограничил включение определенных папок в путь вывода. Рабочий стол - одна из таких папок. Ваш путь вывода не может быть на рабочем столе, даже в подпапке рабочего стола. Моими документами это тоже не может, но МОЖЕТ быть подпапкой моих документов. Если вы получаете ошибки при создании документации, попробуйте изменить путь вывода и посмотрите, исправит ли это. Подробнее см. http://shfb.codeplex.com/discussions/226668?ProjectName=shfb.
Наконец, вам нужно будет добавить ссылку на проект, который вы хотите документировать. Если вы делаете отдельные проекты, как я, то для каждого файла проекта SHFB вы будете ссылаться на соответствующий файл .CSPROJ. Если у вас есть один проект SHFB для всего вашего решения, то вы найдете файл .SLN для вашего решения. (sandcastle также работает, если вы ссылаетесь на скомпилированные библиотеки DLL, но поскольку вы интегрируете его с Visual Studio, я считаю, что вместо этого имеет смысл ссылаться на файлы проекта / решения. Это также может означать, что действительно не имеет значения, какой проект вы выполнить событие после сборки, поскольку оно ссылается на код, а не на библиотеки DLL, но лучше быть в безопасности и поместить его в последний созданный проект)http://www.chevtek.com/Temp/AddSource.jpg
Сохраните проект и закройте «Построитель файлов справки Sandcastle». Теперь все настроено. Обязательно поместите файл проекта документации в соответствующую папку, на которую указывают пакетные команды в событии после сборки.
Надеюсь, мой короткий урок поможет вам! Мне было очень трудно найти какие-нибудь приличные учебники, показывающие, как использовать sandcastle, не говоря уже о том, как интегрировать его с visual studio. Надеюсь, в будущем поиск в Google поднимет этот вопрос.