Apache Forrest как решение для документирования кода

Question

В последнее время я рассматривал Apache Forrest как решение для документирования кода. С сайта Apache,

"Программное обеспечение Apache Forrest ™ является издательская структура, которая трансформируется вход из различных источников в единое представление в одном или нескольких выходные форматы. Модульная и расширяемый плагин архитектуры Apache Forrest основан на Apache Кокон и соответствующая отрасль стандарты, которые разделяют представление из содержания. Форрест может генерировать статические документы, или использоваться в качестве динамический сервер, или развернуть его автоматизированный объект. "

Мне было интересно, можно ли использовать Apache Forrest как способ организации и публикации документации некоторого кода Java, который дополнен комментариями JavaDoc. Я знаю, что JavaDoc может сделать это сам, но я чувствую, что Apache Forrest предоставляет некоторые дополнительные настройки. На веб-сайте Apache я нашел инструкции о том, как включить его в Maven, но, похоже, он специально предназначен для Maven 1.x, и я использую Maven 2. Возможно ли что-то подобное? И если да, то как лучше всего его интегрировать?

Спасибо заранее.

Answer 1

В Документирование проектов с помощью Apache Forrest , автор пишет об Альтернативах Forrest :

Если вы знакомы с Maven, вы можете интересно, почему кто-то будет беспокоиться с Форрестом. Maven делает все Форрест и многое другое полностью автоматизировать вашу сборку, прикрепление отчетов JUnit и CVS и всякие дополнительные полезные информация поверх основной документация. Это даже обеспечивает цели для автоматической установки вашего нового созданный веб-сайт на удаленном хосте.

Я использовал Maven на ряде проекты, и это впечатляет пакет. Кривая обучения не намного хуже, чем у Форреста использовать, и так как вам не нужно учиться Муравей, если вы используете Maven, это возможно еще меньше для создания проекта с нуля. Форрест в целом менее сложным, и если вы этого не сделаете нужно все, что обеспечивает Maven, вы может начать с Форреста и мигрировать в Maven позже, если вам это нужно. Форрест также лучше, если у вас есть существующая система большой сборки на основе Ant: позволяет добавлять в стиле Maven создание сайта постепенно вместо того, чтобы переписывать всю свою сборку скрипты для Maven-ize проекта.

С точки зрения чистой документации альтернативы, еще один солидный вариант с большим количеством открытого сообщества поддержка DocBook. Вы могли бы написать Мануал для 747 с DocBook: это лучший SGML (или XML; там две версии) диалект для техническое письмо. Вариант XML имеет хороший набор стилей от Norman Уолш, который может генерировать HTML, PDF, RTF (Microsoft Word) и другие форматы из источника DocBook. Я думаю, что Форрест Диалект XML охватывает 80 процентов случаи, с гораздо меньшим обучением кривая, но для большого проекта, который также необходимо произвести печать документация, достоинства DocBook рассмотрение. Обратите внимание, что если вы хотите перейти с DocBook, Forrest поддерживает рендеринг подмножества DocBook / XML тоже, но это не так хорошо поддерживается. Форрест не стремится стать полноценным DocBook рендеринг в любое время в будущем, либо, согласно одному из разработчики, поэтому я бы не стал полагаться на это как формат для новой документации в Форресте.

Итак, поскольку вы уже используете Maven, мне действительно интересно, почему вы посмотрите на Форреста. Проверьте Maven Doxia , если у вас все еще есть некоторые сомнения относительно потенциала Maven.

И если вы хотите использовать DocBook, и если встроенная поддержка Maven через Doxia слишком ограничена, есть Docbkx Maven Plugin (предпочтительнее, чем Maven Docbook ). *