Классовые документы предложения

Question

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

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

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

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

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

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

Answer 1

Взгляни на Сборщик справочных файлов Sandcastle. Анкет Это использует автономные проекты, поэтому вы можете создавать их так часто, как вам нравится (например, ночь или как часть вашего Непрерывная интеграция Система каждый раз, когда зарегистрируется изменение).

Answer 2

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

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

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

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

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

Answer 3

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

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