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

https://stackoverflow.com/questions/211693

03-07-2019
|

Вопрос

Какие шаги мне нужно предпринять, чтобы получить автоматическую сборку HTML-документации на этапе сборки в Visual Studio?У меня есть все комментарии, сгенерированный файл comments.xml и установленный 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".Таким образом, вы не будете ждать вечно, когда будете выполнять сборку в режиме "Debug" во время разработки.

Пара заметок:

Моя система 64-разрядная, если ваша нет, то замените framework64 с framework на пути к msbuild.exe.
Способ, которым я это настраиваю, заключается в том, чтобы документировать каждый проект в моем решении индивидуально.Если у вас есть файл проекта "Sandcastle Help File Builder", который включает в себя несколько проектов вместе, то вы, вероятно, захотите избавиться от ProjectName\ и двигаться doc в каталог решений.В этом случае вам захочется размещать команды событий после сборки только в том проекте, который создается ПОСЛЕДНИМ в вашем решении.Если вы добавите это в событие Post-build для каждого проекта, то вы будете перестраивать свою документацию для каждого созданного проекта.Излишне говорить, что вам придется посидеть там некоторое время.Лично я предпочитаю документировать каждый проект по отдельности, но это касается только меня.

Установка Sandcastle и "Конструктора файлов справки Sandcastle".

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

Скачайте и установите Sandcastle с сайта http://sandcastle.codeplex.com/ (если у вас 64-разрядная система, вам нужно будет добавить переменную окружения.Инструкции таковы здесь.
Загрузите и установите "Конструктор файлов справки Sandcastle" с сайта http://shfb.codeplex.com/ (игнорируйте предупреждения о MSHelp2, если вы их получите.Вам это не понадобится.)
Как только они будут установлены, используйте "Sandcastle Help File Builder" для создания нового проекта документации.Когда он спросит вас, куда сохранить файл, сохраните его в папке documentation, которая есть в вашем решении / проекте.http://www.chevtek.com/Temp/NewProject.jpg
После создания нового проекта вам нужно будет выбрать, какой тип документации вы хотите создать.Скомпилированный файл справки Windows, веб-сайт или и то, и другое.http://www.chevtek.com/Temp/DocumentationType.jpg
Если вы сохранили файл проекта SHFB в каталоге, в котором хотите сгенерировать документацию, то можете пропустить этот шаг.Но если вы хотите, чтобы сгенерированная документация была размещена в другом месте, тогда вам нужно настроить путь вывода.http://www.chevtek.com/Temp/OutputPath.jpg ПРИМЕЧАНИЕ:Одна вещь, которую следует иметь в виду относительно пути вывода (что расстраивало меня в течение часа), заключается в том, что когда вы проверяете веб-сайт как нужный вам тип документации, он перезаписывает содержимое в своем пути вывода.Что они забывают сообщить вам, так это то, что SHFB намеренно запретил включение определенных папок в качестве части выходного пути.Рабочий стол - одна из таких папок.Ваш выходной путь не может находиться на рабочем столе, даже в подпапке desktop.Это также не может быть связано с моими документами, но это МОЖЕТ быть вложенная папка "мои документы".Если вы получаете ошибки при создании документации, попробуйте изменить путь вывода и посмотрите, исправит ли это проблему.Видишь 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 выявят этот вопрос.

Другие советы

Я рекомендую вам установить конструктор файлов справки Sandcastle со страницы Codeplex .

Вы можете запустить это из командной строки, например, из события после постройки. Самая простая командная строка:

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

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

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

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

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

MSbuild.exe ProjectName.shfb

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

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

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

[edit] отмечен, и да - 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 = ен

Затем используйте командную строку NDocConsole.exe, чтобы сгенерировать документацию в форме MSDN или CHM:

@c: \ progra ~ 1 \ NDoc \ NDocConsole.exe MyCode.dll, MyCode.xml -Documenter = MSDN-CHM

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

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

Лицензировано под: CC-BY-SA с атрибуция

Не связан с StackOverflow