Создание HTML-документации автоматически во время сборки с Sandcastle

С тех пор, как был задан этот вопрос, были внесены некоторые изменения. 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 для каждого проекта, вы будете перестраивать документацию для каждого построенного проекта. Излишне говорить, что вы посидите там некоторое время. Лично я предпочитаю документировать каждый проект индивидуально, но это только я.

установка Sandcastle и " файл справки Sandcastle Строитель."

если вы не знаете, как правильно настроить Sandcastle и "Sandcastle Help File Builder", выполните следующие действия:

1. Загрузите и установите Sandcastle из http://sandcastle.codeplex.com/ (Если у вас 64-разрядная система, вам нужно будет добавить переменную среды. Инструкции здесь.

2. Загрузите и установите "Sandcastle Help File Builder" из 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 намеренно ограничил некоторые папки от включения в качестве части выходного пути. Desktop-одна из таких папок. Путь вывода не может быть на рабочем столе, даже в подпапке рабочего стола. Это также не может быть моими документами, но это может быть подпапка Моих документов. Если вы получаете ошибки при создании документации, попробуйте изменить путь вывода и посмотреть, исправляет ли это его. Вижу http://shfb.codeplex.com/discussions/226668?ProjectName=shfb для получения дополнительной информации.

6. наконец, вам нужно будет добавить ссылку на проект, который вы хотите документировать. Если вы делаете отдельные проекты, как я, то для каждого файла проекта SHFB вы создать, Вы будете ссылаться на соответствующий .Файл CSPROJ. Если у вас есть один проект SHFB для всего вашего решения, вы найдете его .SLN файл для вашего решения. (sandcastle также работает, если вы ссылаетесь на скомпилированные библиотеки DLL, но поскольку вы интегрируете его с Visual Studio, я считаю, что имеет смысл ссылаться на файлы проекта/решения. Это также может означать, что на самом деле не имеет значения, в каком проекте вы выполняете событие после сборки, поскольку он ссылается на код вместо Dll, но лучше быть в безопасности и поместить его в последний построенный проект) http://www.chevtek.com/Temp/AddSource.jpg

7. сохраните проект, и вы можете закрыть "Sandcastle Help File Builder". Теперь все готово. Просто не забудьте поместить файл проекта документации в соответствующую папку, на которую указывают пакетные команды в событии после сборки.

Я надеюсь, что мой короткий учебник поможет вам! Мне было очень трудно найти любые приличные учебники, показывающие мне, как использовать sandcastle, не говоря уже о том, как интегрировать его с visual studio. Надеюсь, в будущем поисковые запросы google поднимут этот вопрос.