Недавно я (наконец) стал документировать один из моих проектов с открытым исходным кодом. Проект представляет собой библиотеку классов для .Net. Я использую Doxygen для создания документации HTML из исходного кода.
Теперь, мой вопрос, должен ли я хранить файлы HTML, которые Doxygen производит в моем исходном элементе управления?
Как вы думаете, вы сможете перестраивать документацию каждый раз, когда вы совершаете код? В противном случае ваша документация быстро станет ненадежной, поскольку она может или не может быть синхронизирована с вашим кодом.
Но я понимаю, что это трудное решение, потому что, особенно если ваш проект запущен/мал, у вас нет инфраструктуры для сервера автоматической сборки (поэтому вы не можете предлагать синхронизированную сгенерированную документацию онлайн) и оставляете это для пользователей означает, что вы вынуждаете их устанавливать Doxygen.
Мое решение (как я делаю это с моим проектом):
Не размещайте сгенерированную документацию под контролем версий
Записывайте сценарии, которые легко сгенерируют документацию, просто запустив их для всех целевых платформ (BAT для Windows, Sh for * nix), если установлен инструмент генерации источника, снабдите их исходными кодами. Хорошая идея - попросить пользователей установить инструмент (и указать URL), если он не установлен.
Лучше делать релизы чаще, чем не с скомпилированными двоичными файлами и сгенерированной документацией, даже если ваша программа все еще находится на ранних стадиях разработки. Но если это так, дайте понять пользователям, загружающим пакет. Никогда не наклеивайте багги/половину версии 1.0! Пользователи попробуют вашу программу/библиотеку, рассматривают ее как проблемную и никогда не дают ей шанс снова!
EDIT:
Я вижу, что вы используете .NET. Считаете ли вы использование Sandcastle? Это инструмент для документации, разработанный Microsoft специально для .NET. Я думаю, что я создаю гораздо лучшие файлы справки, чем Doxygen - примером его использования является полная библиотека документации MSDN.NET:)
Его недостатком является то, что процесс генерации на порядок медленнее, чем Doxygen's. Это не проблема, если вы делаете это только при выпуске, но было бы очень непрактично, если бы вы хотели сгенерировать помощь перед каждой фиксацией (которая меняет API).
Ничего сгенерированного не должно идти в исходное управление. Некоторая дискуссия на эту тему: http://damienkatz.net/2005/12/generated_code.html
Комментарий из сообщения:
Обычно считается, что сгенерированный исходный код был проверен в источнике управления по той же причине, что и вы не проверяете двоичные файлы. Процесс сборки создает файлы, поэтому они являются результатом сборки, а не управляемым исходным кодом. Это пуристский идеал.
Если другие разработчики используют вашу библиотеку, они проверяют исходный код и заранее создают библиотеку? Если да, то процесс сборки автоматически генерирует файлы doc? Если ответ два раза да, тогда вам не нужно помещать файлы HTML в исходный код.
Если нет, и вам нужно сделать больше ручных шагов для доступа к документам, добавление файлов в исходный контроль будет вариантом. Другая причина может заключаться в том, что процесс сборки doc очень медленный.
Тем не менее, IMHO - это хорошая идея организовать процесс сборки таким образом, чтобы документы создавались полностью автоматически.
Один вариант, который еще не упоминался:
Если вы не уверены, что сможете восстановить документацию (потому что вы не всегда будете в среде со всеми необходимыми инструментами для этой задачи), я бы:
любая версия один сжатый файл, представляющий всю документацию (она быстрее, как для добавления в исходный элемент управления, так и для извлечения при проверке).
Но это только в том случае, если упомянутая документация не изменится очень сильно с этого момента (в противном случае вы снова и снова будете использовать большой двоичный файл, который VCS не очень хорош)
или сохраните доставку вне инструмента VCS в двоичном репозитории (например, Nexus например), причем указанная доставка составляет:
Таким образом (т.е. "внешний репозиторий артефактов" ), я знаю, что могу получить все: