Предложения по документации класса

Question

Мы магазин Microsoft, сконцентрированный на использовании C #.У нас есть несколько проектов, включая веб-сайты, службы Windows и библиотеки классов, которые включают комментарии XML.

Я хочу сгенерировать HTML-документацию в стиле MSDN для каждого проекта и развернуть ее в централизованном месте, к которому все разработчики могут легко получить доступ.Я также хочу автоматизировать эти шаги, чтобы они могли выполняться через равные промежутки времени, поэтому мне и другим разработчикам не нужно беспокоиться о том, чтобы не забывать создавать и развертывать новую документацию при каждом изменении.Я посмотрел на Sandcastle и Doxygen, и оба они выглядят хорошими вариантами для создания документации, которую я хочу, но мне нужен совет по хорошему способу автоматизации его генерации, например, на ночной работе или что-то в этом роде.

Кто-нибудь делает что-то подобное?Я не продан в конечном результате HTML;особенно если есть идея получше.

РЕДАКТИРОВАТЬ:

Я ценю все хорошие идеи.Сейчас есть несколько путей, которые я могу исследовать, но я не буду знать, какие из них будут работать лучше, пока не испачкаю руки.Построитель файлов справки Sandcastle, кажется, предлагает мне лучшие варианты того, что я собираюсь сделать, поэтому я дам добро на это предложение.Однако, если бы у меня было больше времени поработать над решением XSLT и CSS, чтобы XML-данные выглядели правильно, я бы в первую очередь воспользовался этим предложением.

Еще раз спасибо всем!

Answer 1

Вам не нужны никакие сторонние инструменты для генерации красивой документации: компилятор C # может выводить документацию из XML-комментариев в формате XML, и все, что вам нужно, - это создать красивый CSS для отображения в браузере.Если вы не удовлетворены, вы также можете сгенерировать свое собственное XSLT-преобразование перед применением CSS, , как описано здесь (ищите пример CSS в комментариях!).

В качестве альтернативы вы можете взятьэту документацию XML и улучшите ее, используя что-то вроде NDoc .Вот хорошая статья о том, как это сделать, к сожалению, несколько устаревшая.

Вы можете вручную собрать только документацию вашего проекта в один файл XML, запустив компилятор с /doc:documentationfilename.xmlпараметр.

Вы также можете указать в Visual Studio (Свойства проекта -> Документация) добавить эту опцию в каждую сборку вашего проекта, чтобы XML-файл создавался при каждой сборке проекта.Затем вы можете подключить события после сборки, чтобы скопировать XML-файл в ваш репозиторий.

Вы также можете настроить MS Build на своем Team Foundation Server, чтобы создавать свою документацию и копировать ее в хранилище аналогичным образом (/p:DocumentationFile=fileName.xml);

Answer 2

Взгляните на Sandcastle Help File Builder .При этом используются автономные проекты, поэтому вы можете создавать их столько раз, сколько захотите (например, ночью или как часть вашей системы непрерывной интеграции каждый раз, когда регистрируется изменение).

Answer 3

Я делаю это с нашими проектами. В основном мы используем doxywizard, чтобы настроить конфигурационный Doxyfile, который установит спецификации для сгенерированного html. Затем на шаге сервера сборки я вызываю «doxygen doxyfile».

Наш Doxyfile сконфигурирован для генерации файлов doxygen в области, видимой с нашего веб-сервера. Таким образом, каждый коммит в транк заставляет документацию перестраиваться автоматически.