Создавайте документацию html автоматически во время сборки с помощью Sandcastle

Ответ 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 появятся в этом вопросе.

Ответ 2

Я рекомендую вам установить Builder Builder для Sandcastle из Codeplex.

Вы можете запустить это из командной строки, например. из события Post-Build. Простейшая командная строка:

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

Песочница очень медленная, поэтому я запускаю ее только для выпусков сборки. Для этого создайте событие Post-Build с командой следующего вида, которая передает имя конфигурации в пакетный файл:

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

Затем внутри командного файла вы можете проверить, является ли первый аргумент "Release", и если так запустить SandcastleBuilderConsole.exe.

Ответ 3

Простым способом сделать это, как было предложено выше, является использование Sandcastle Help File Builder. Были внесены некоторые изменения в процесс сборки из командной строки, и теперь эти проекты могут быть созданы с помощью MSbuild вместо SandcastleBuilderConsole.exe. Итак, все, что вам нужно сделать, это:

MSbuild.exe ProjectName.shfb

Ответ 4

Я должен признать, что я считаю, что текущая версия Sandcastle немного отсутствует; для крупных проектов он довольно медленный, и его непросто интегрировать (поскольку он еще рано).

Для обычного использования я нахожу проще просто отражать отражатель в папке с файлами dll и xml - IIRC, он будет загружать xml файл во время навигации по нему.

Плюс у меня почти всегда есть отражатель, открытый в любом случае...

[edit], а да - комментарии xml отображаются на панели дизассемблера

Ответ 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

Я сам внедрил внешний инструмент для этого и дал ему ярлык, но, поскольку предыдущий плакат сказал, что вы можете подключить его к событию postbuild, и там вы идете.

(PS Я уже несколько лет использую установку выше и очень доволен ею)