Создайте документацию по руководству пользователя с Maven

Question

Мне нужно написать и построить легко поддерживаемую, удобную, удобную для изменения документации в формате pdf и html 5. Формат источника должен быть легко отредактирован. Этот плагин maven должен поддерживать мою компанию organziation theam (шрифты, цвета, рисунки и т. Д.), Генерация TOC, разделение глав в разных файлах, интеграция файлов изображений, простой способ поместить код snipets в документацию. У меня есть Maven build, и мне было интересно, каково нынешнее лучшее решение для этого?

Я был расследовать два варианта:

• Doxia - с помощью MD (уценки) в качестве входного формата. Существует WSWG md free редактор, поддержка многих продуктов и т. Д. Требуется внешний репо для его артефактов.
• Asciidoctor - используйте asdcii doc в качестве входного формата. Поддержка шаблонов с использованием фрагментов и т. Д.

Каковы преимущества и недостатки использования этих плагинов? Есть ли другие хорошие решения?

Answer 1

Из моих попыток построить документацию сначала с Doxia, а затем с AsciiDoc Я понял, что Asciidoc лучше. Это позволяет

• Простое моделирование с использованием YAML файлов. Default укладка тоже очень хорошо.
• Asciidoc как язык наценка очень хорошо документированы: Uder Guide AsciiDoc
• Имеет хороший онлайн editors и язык является более мощным, чем уценки, например, и проще писать по сравнению с форматом XML .
• Хорошо examples при использовании с Maven и ascii doc и легко понять configurations.