Создание документации с maven

Question

Я только что посещу maven. У нашей команды был плохой опыт, когда мы в последний раз смотрели на это, как это было в период, когда maven была перестроена с 1.x до 2.x, поэтому многие необходимые нам зависимости не были перенесены в новые репозитории , Однако у меня есть время пересмотреть сейчас.

Я заинтересован в использовании Maven и либо LaTeX или DocBook для создания документации, и мне было интересно, если кто-либо поделиться своим опытом, структура проекта/модуль, хорошие плагины использовать и т.д ...

Многие спасибо :-)

Edit:

Просто чтобы прояснить, я искал написать техническую статью/книгу, и мой желаемый артефакт, вероятно, будет PDF.

Answer 1

Недавно я реализовал проектную документацию для моего мультимодульного проекта maven с помощью docbook и плагина docbkx для maven. Теперь я автоматически создаю файлы html и pdf каждый раз при создании сайта проекта. Я думаю, что docbkx действительно качается, поэтому я предлагаю вам использовать это.

Его правда - вы можете создать очень хороший сайт, используя только сайт maven и плагины doxia. На самом деле я использую эти два для создания моего сайта проекта. Но поддержка doxia для docbook очень ограничена и, например, не позволяет вам модулизовать документацию, включая части документов в основном документе. Поэтому для больших справочных руководств я использую docbkx.

Если вы хотите заглянуть, мой проект here. Вы можете загрузить исходный код и посмотреть на него. И, конечно, если у вас возникнут какие-либо вопросы относительно этой установки, я буду более чем рад помочь.

Приветствия Carlos

Answer 2

Вы можете легко создать сайт (содержащий документацию) с Maven, используя команду mvn site (т. Е. Используя plugin site).

Этот плагин создает технические отчеты (такие как Javadoc, отчеты об испытаниях модулей, покрытие кода ...), но также может использоваться для создания «реального сайта». У вас есть более подробная информация об этом в this page.

В принципе, вы пишете свою страницу с помощью APT (Почти обычного текста который довольно прост для понимания), или формат XML на основе, Xdoc.

2 года назад я создал полное руководство пользователя для одного приложения, которое я разработал, используя формат XDoc и плагин Site Maven. В глобальном масштабе это было довольно легко создать!

Надеюсь, это поможет!

Answer 3

Существует не официальный или полуофициальный плагин AFAIK, который будет обрабатывать LaTeX или DocBook, но то, что вы могли бы сделать (помимо использования вышеупомянутого плагина сайта), - это настроить плагин exec для обработки ваших источников LaTeX/DocBook во время сайта жизненного цикла, то есть в то же время, когда строится веб-сайт проекта.

например, что-то вроде

<plugin> 
    <groupId>org.codehaus.mojo</groupId> 
    <artifactId>exec-maven-plugin</artifactId> 
    <executions> 
    <execution> 
    <id>latex</id> 
    <goals> 
     <goal>exec</goal> 
    </goals> 
    <phase>site</phase> 
     <configuration> 
      ... 
     </configuration> 
    </execution> 
    </executions> 
</plugin> 

Answer 4

DocBook является одним из многих поддерживаемых входов в Doxia, двигатель, используемый для генерации документации от мавена. См здесь: http://maven.apache.org/doxia/modules/index.html

В самом деле, сайт Doxia отвечает на ваш точный вопрос: http://maven.apache.org/doxia/book/index.html

Answer 5

Я использую с успехом Maven плагин Docbkx. Вы должны дать ему попробовать

Docbkx

Answer 6

Вы определенно должны взглянуть на Maven Docbkx Plugin. Это, вероятно, соответствует вашим потребностям. Поддержка Doxia DocBook -ум-субоптимальная. Фактически, в прошлый раз, когда я это пробовал, он создал что-то новое, что, насколько я могу судить, не было DocBook.

Плагин Maven Docbkx, который я имею в виду, поддерживает все настройки мира (с помощью параметров плагина или переопределения XSLT, если вы в этом) + в нем есть некоторые механизмы для его интеграции с сборкой Maven. (Например, инструкции по обработке для включения свойств Maven pom в ваши документы.)

Обратите внимание, что цель состоит в том, чтобы иметь плагин, который мешает вам вручную собрать цепочку обработки самостоятельно. Таким образом, этот плагин будет делать преобразование в FO и преобразовывать его в PDF.

Answer 7

Хотя вопрос довольно старый, я хочу, чтобы дать обновление по этому вопросу. Если вы хотите использовать LaTeX для своей документации, вы должны использовать плагин maven для создания документации. Есть пара maven-плагинов, которые делают это, но многие из них больше не поддерживаются. Существует новый maven-плагин, который не требует конфигурации или конфигурации, чтобы заставить его работать, и сгенерированный PDF (или PS или DVI) можно опубликовать как артефакт.

Посмотрите: mathan-latex-maven-plugin