Какие шаги необходимо предпринять, чтобы получить документацию HTML, автоматически создаваемую с помощью этапа сборки в Visual Studio? У меня есть все комментарии и созданный файл comments.xml, и Sandcastle установлен. Мне просто нужно знать, что добавить к этапу после сборки, чтобы генерировать документы.Создавать документацию html автоматически во время сборки с помощью Sandcastle
Некоторые изменения были сделаны, так как этот вопрос был задан. Sandcastle больше не включает SandcastleBuilderConsole.exe. Вместо этого он использует простой старый MSBuild.exe.
Чтобы интегрировать это с визуальной студии, вот что я сделал:
Место это в пост-сборки событие:
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», который включает несколько проектов вместе, то вы, вероятно, захотите избавиться от ProjectName\ и переместите doc в каталог решений. В этом случае вы захотите только поместить команды события Post-build в проект, который построен LAST в вашем решении. Если вы поместите его в событие Post-build для каждого проекта, вы будете перестраивать свою документацию для каждого проекта, который был построен. Излишне говорить, что вы будете сидеть там некоторое время. Лично я предпочитаю документировать каждый проект по отдельности, но это только я.
Установка Sandcastle и "Sandcastle Help Builder File".
Если вы не знаете, как получить Sandcastle и настройка «Sandcastle Builder файл справки» правильно, то выполните следующие действия:
Скачать и установить Sandcastle из http://sandcastle.codeplex.com/ (если у вас есть 64 бит системе, вам нужно будет добавить переменное окружение. инструкции here.
Скачать и установить «Сандкасла Builder Help File» из http://shfb.codeplex.com/ (игнорировать предупреждения о MSHelp2 если вы получаете какое-либо. вы не будете нуждаться в его.)
После того, как вы установили эти параметры, используйте «Builder 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
Сохранить проект, и вы можете закрыть «Sandcastle Помощь File Builder ". Теперь все настроено. Просто обязательно поместите файл проекта документации в соответствующую папку, на которую указывают командные команды в событии Post-build.
Надеюсь, мой короткий учебник поможет вам! Мне было очень трудно найти приличные уроки, показывающие, как использовать sandcastle, не говоря уже о том, как интегрировать его с визуальной студией. Надеемся, что в будущем поисковые запросы Google появятся в этом вопросе.
Я рекомендую установить Sandboxle Help File Builder с Codeplex.
Вы можете запустить это из командной строки, например. из события Post-Build. Простейшей командной строкой является:
<install-path>\SandcastleBuilderConsole.exe ProjectName.shfb
Sandcastle очень медленный, поэтому я запускаю его только для релизов сборки. Чтобы сделать это, создать событие после сборки с командой что-то вроде следующего, который передает имя конфигурации в пакетном файле:
CALL "$(ProjectDir)PostBuild.cmd" $(ConfigurationName)
Затем внутри пакетного файла, который вы можете проверить, если первый аргумент «Release ", и если так запустить SandcastleBuilderConsole.exe.
Я делаю это уже в сценарии пост-сборки, я просто проверяю имя конфигурации, чтобы убедиться, что это «Документация» (у меня есть 3 конфигурации, отладка, выпуск и документация). – 2008-10-17 11:03:33
Еще лучше. Значит, вы можете быстро создавать версии релизов без документа. – Joe 2008-10-17 11:06:27
Должен признаться, что я считаю, что текущая версия Sandcastle немного отсутствует; для крупных проектов он довольно медленный, и его непросто интегрировать (поскольку еще рано).
Для регулярного использования я нахожу проще просто указывать отражатель в папке с файлами dll и xml - IIRC, он будет загружать xml-файл (ы) при перемещении по нему.
Плюс я почти всегда рефлектор открыть в любом случае ...
[править] проверена, и да - XML комментарии показать на панели дизассемблера
Установите эти:
NDoc: http://prdownloads.sourceforge.net/ndoc/NDoc-v1.3.1.msi?download
HTML Help Workshop: 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 Я использую настройки выше в течение нескольких лет, и я очень счастлива с ним)
Простой способ сделать это, как предложено выше, с помощью Sandcastle Help File Builder. Были внесены некоторые изменения в процесс сборки из командной строки, и теперь эти проекты могут быть созданы с помощью MSbuild вместо SandcastleBuilderConsole.exe. Так что все, что вам нужно сделать, это:
MSBuild.exe ProjectName.shfb
Не знаю, сколько времени вы планируете строить, но просто хотел упомянуть, что sandcastle действительно не то, что вы хотите включить в свой обычный цикл отладки. – 2008-10-21 06:59:03
Нет, как я упоминал в этом ответе (http://stackoverflow.com/questions/211693/generate-html-documentation-automatically-during-a-build-with-sandcastle#211710) У меня есть отдельная сборка для документации. – 2008-10-21 08:08:33