Мощный инструмент для создания документации (точные требования включены)
Укороченная версия
Нам нужна альтернатива Maven Doxia, способная генерировать хорошо выглядящие PDF-файлы (по крайней мере, фрагменты кода должны иметь правильный отступ и иметь настраиваемый размер шрифта). Парни Maven предложили maven-pdf-plugin в DOXIA-419, но у него те же проблемы. Вышеупомянутый DOXIA-419 содержит подробную информацию о трудностях, с которыми мы столкнулись при работе с Doxia.
Подробная версия
Мы разрабатываем БОЛЬШОЙ продукт, предоставляющий API Java/C/C++/C#/etc. Десятки клиентских филиалов обслуживаются / развиваются одновременно. Нам нужен инструмент для облегчения автоматической генерации документов, отвечающий этим требованиям:
Включите произвольные фрагменты из примеров Java/XML/etc. Confluence Snippet Plugin является хорошим примером этой функции.
Создавайте хорошо выглядящие печатные документы (например, PDF).
Создание онлайн-документов с перекрестными ссылками и т. Д. (Например, HTML).
Автоматический режим (например, должно быть легко запустить процесс создания документа из скрипта Ant).
Исходный контент документации (из которого впоследствии создаются PDF-файлы и т. Д.) Должен храниться в удобном для восприятия формате.
Содержание исходного документа должно храниться в отдельных файлах (не в источниках Java).
Поддержка (Java/xml/etc) подсветки синтаксиса.
ОБНОВЛЕНИЕ: 8. Совместимость с ОС Windows.
1 ответ
Мой проект с открытым исходным кодом Dexy может работать для вас. Это скорее инструмент разработки, а не инструмент автоматического создания документов, поэтому он не похож на JavaDoc, который создает целую структуру автоматически. Исходный код и содержимое документа хранятся отдельно, поддержка подсветки синтаксиса очень хорошая, доступны фрагменты документа. Я использую LaTeX для красивых документов для печати, но вы можете использовать любой другой текстовый формат, скомпилированный в PDF, если вы предпочитаете это. Что касается кликабельных перекрестных ссылок, вам нужно написать HTML-шаблоны, которые затем можно будет заполнить автоматически (я делаю это сейчас, заменяя JavaDoc в проекте). Вы также можете запустить примеры кода в реальном времени и включить этот вывод в свою документацию.