Ответ 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
Это заставит визуальную студию создавать вашу документацию только в том случае, если вы создадите режим "Release". Таким образом, вы не будете ждать всегда, когда будете строить в режиме "Отладка" во время разработки.
Несколько примечаний:
-
Моя система является 64-разрядной, если вместо этого вы не замените
framework64наframeworkв пути кMSBuild.exe. -
У меня есть настройка для документирования каждого проекта в моем решении по отдельности. Если у вас есть файл проекта "Sandcastle Help File Builder", который включает несколько проектов вместе, то вы, вероятно, захотите избавиться от
ProjectName\и переместитьdocв каталог решений. В этом случае вы захотите только поместить команды события Post-build в проект, который построен LAST в вашем решении. Если вы поместите его в событие Post-build для каждого проекта, вы будете перестраивать свою документацию для каждого проекта, который был построен. Излишне говорить, что вы будете сидеть там некоторое время. Лично я предпочитаю документировать каждый проект по отдельности, но это только я.
Установка Sandcastle и "Builder Builder" в программе Sandcastle.
Если вы не знаете, как правильно настроить Sandcastle и "Sandcastle Help File Builder", выполните следующие действия:
-
Загрузите и установите Sandcastle с http://sandcastle.codeplex.com/ (если у вас 64-битная система, вам нужно будет добавить переменную окружения Инструкции здесь.
-
Загрузите и установите "Builder Builder в Sandcastle" из http://shfb.codeplex.com/ (игнорируйте предупреждения о MSHelp2, если вы их получите. ему это нужно.)
-
После того, как вы установили эти файлы, используйте "Sandbule Help File Builder", чтобы создать новый проект документации. Когда он спросит вас, где сохранить файл, сохраните его в папке документации, имеющейся в вашем решении/проекте. 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
-
Сохраните проект, и вы можете закрыть "Sandbule Help File Builder". Теперь все настроено. Просто обязательно поместите файл проекта документации в соответствующую папку, на которую указывают командные команды в событии Post-build.
Надеюсь, мой короткий учебник поможет вам! Мне было очень трудно найти приличные уроки, показывающие, как использовать sandcastle, не говоря уже о том, как интегрировать его с визуальной студией. Надеемся, что в будущем поисковые запросы Google появятся в этом вопросе.