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

Question

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

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

Большое спасибо: -)

Edit:

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

Answer 1

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

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

Answer 2

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

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

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

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

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

Answer 3

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

Docbkx

Answer 4

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

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

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

Answer 5

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

Взгляните на: mathan-latex-maven-plugin

Answer 6

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

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

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

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

Answer 7

У 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>