Использование Maven для ведения документации пользователя

Question

Мы используем Maven для создания приложения в стиле сервера Java. Он состоит из нескольких модулей (в одном реакторе Maven), которые могут быть подключены вместе для создания конечного продукта (в основном, .jar) с функциями, которые могут быть необходимы клиенту. Все внутренние документы документируются с использованием JavaDoc и всех, но это не то, что вы можете дать клиенту, чтобы узнать, как это сделать. В настоящее время у нас есть документ OpenOffice, который служит документацией для конечных пользователей.

Я хотел бы интегрировать эту документацию в процесс сборки Maven, где поддерживаются документация каждого модуля (вручную) вместе с источниками модуля, а заключительный документ может ссылаться на необходимые разделы документации модуля, добавлять дружеские предисловия и , если возможно вообще, может ссылаться на JavaDocs. В конечном итоге документ должен выводиться как PDF.

Есть ли какие-либо впечатления от плагинов Maven, это может помочь? Является ли DocBook правильным инструментом? Может быть, латекс? Или что-то совсем другое? Звуковой «палкой с OpenOffice и некоторыми текстовыми блоками» также может быть ответ.

Answer 1

Я предполагаю, что вы еще не посмотрели Maven site documentation generation с maven-site-plugin. Он довольно надежный и позволит вам включать и включать в себя генерирование JavaDoc, а также контент из вашего документа OpenOffice.

В то время как документация по сайту не выводится как PDF, она, однако, выводится как статический HTML-сайт с множеством встроенных возможностей. Используя профили Maven, вы можете настроить Maven для создания одного сайта для внутреннего использования, который включает Результаты испытаний Surefire и другие отчеты для проверок типа Checkstykle и PMD. В другом профиле вы можете настроить его только для генерации документации, необходимой для распространения, для клиентов, которая не включает внутренние отчеты, которые могут не беспокоить клиенты.

Одно замечание, хотя, большая часть генерации документации на сайте меняется Maven 3. В то время как большинство из Maven 3 обратно совместим с Maven 2, помнить об изменениях отчетности для Maven 3. Проверьте эти ссылки:

• Site Generation Compatibility
• Converting maven-site-plugin for Maven 3

Answer 2

и в случае, если сайт плагин с внешними Docs не производит достаточно высокого качества, вы можете использовать DocBook с Maven для создания HTML и вывода PDF. На самом деле Sonatype делает это для всех своих книг (например, Maven: The Complete Reference, Nexus book, M2Eclipse book ...), и они имеют открытый исходный код, поэтому вы можете увидеть, как все это работает, и скопировать настройку и изменить ее для ваших нужд. Преимущество использования docbook в том, что инструментарий довольно хорош (например, xmlmind) и что он выпускает книги с качеством печати с индексом, током и т. Д.

О, и так как вы упомянули, это есть также LaTeX плагин для Maven, но у меня нет опыта работы с ним (но совсем немного с латексом перед моим использованием Maven ...)

Answer 3

Другим решением является Maven docbkx плагин для преобразования DocBook в PDF; HTML и т. Д.

Прочтите это описание о том, как добавить преобразованный DocBook to HTML на сайт проекта Maven, если вы хотите, чтобы ваш контент DocBook также отображался на созданном Maven сайте.

Интересные смежные вопросы:

• What is the recommended tool chain for formatting XML DocBook?.

Answer 4

У меня есть мультимодульный проект maven, в котором каждый модуль имеет свое собственное справочное руководство, написанное в формате docbook. И тогда у меня есть общее справочное руководство, также написанное в docbook, которое включает других, поэтому я повторно использую документацию. Когда я выполняю mvn-сайт, проект создает файлы HTML и PDF со всеми справочными руководствами, и они аккуратно интегрированы в сайт maven. Для этого я использую плагин docbkx. Я думаю, что это действительно потрясает. Вот конфигурация плагина:

  <plugin> 
      <groupId>com.agilejava.docbkx</groupId> 
      <artifactId>docbkx-maven-plugin</artifactId> 
      <executions> 
       <execution> 
        <id>docbook-HTML</id> 
        <phase>pre-site</phase> 
        <goals> 
         <goal>generate-html</goal> 
        </goals> 
        <!-- HTML configuration --> 
        <configuration> 
         <generateToc>false</generateToc> 
         <targetDirectory>${project.build.directory}/site</targetDirectory> 
         <htmlCustomization>${basedir}/src/site/docbkx-config/docbook-html.xsl</htmlCustomization> 
         <htmlStylesheet>./css/apache-maven-fluido-1.3.0.min.css</htmlStylesheet> 
         <chunkedOutput>false</chunkedOutput> 
        </configuration> 
       </execution> 
       <execution> 
        <id>docbook-PDF</id> 
        <phase>pre-site</phase> 
        <goals> 
         <goal>generate-pdf</goal> 
        </goals> 
        <!-- PDF configuration --> 
        <configuration> 
         <generateToc>true</generateToc> 
         <paperType>A4</paperType> 
         <imgSrcPath>file:///${basedir}/src/site/resources/</imgSrcPath> 
         <calloutGraphicsPath>file:///${basedir}/src/site/resources/images/callouts/</calloutGraphicsPath> 
         <calloutGraphicsExtension>.svg</calloutGraphicsExtension> 
         <calloutGraphicsNumberLimit>30</calloutGraphicsNumberLimit> 
         <calloutIconSize>6</calloutIconSize> 
         <shadeVerbatim>true</shadeVerbatim> 
         <targetDirectory>${project.build.directory}</targetDirectory> 
         <foCustomization>${basedir}/src/site/docbkx-config/docbook-fo.xsl</foCustomization> 
         <!-- <bodyFontFamily>Kaffeesatz</bodyFontFamily> 
         <monospaceFontFamily>LiberationMono</monospaceFontFamily> 
         --> 
         <fonts> 
          <font> 
           <name>Kaffeesatz</name> 
           <style>normal</style> 
           <weight>normal</weight> 
           <embedFile>${basedir}/src/fonts/YanoneKaffeesatz-Regular.ttf</embedFile> 
           <metricsFile>${basedir}/target/fonts/YanoneKaffeesatz-Regular-metrics.xml</metricsFile> 
          </font> 
          <font> 
           <name>LiberationMono</name> 
           <style>normal</style> 
           <weight>normal</weight> 
           <embedFile>${basedir}/src/fonts/LiberationMono-Regular.ttf</embedFile> 
           <metricsFile>${basedir}/target/fonts/LiberationMono-Regular-metrics.xml</metricsFile> 
          </font> 
          <font> 
           <name>VeraMono</name> 
           <style>normal</style> 
           <weight>normal</weight> 
           <embedFile>${basedir}/src/fonts/VeraMono.ttf</embedFile> 
           <metricsFile>${basedir}/target/fonts/VeraMono-metrics.xml</metricsFile> 
          </font> 
         </fonts> 
        </configuration> 
       </execution> 
      </executions> 
      <!-- Shared configuration --> 
      <configuration> 
       <sourceDirectory>${basedir}/src/site/docbkx</sourceDirectory> 
       <includes>*.xml</includes> 
       <xincludeSupported>true</xincludeSupported> 
       <generatedSourceDirectory>${project.build.directory}/site</generatedSourceDirectory> 
       <highlightSource>1</highlightSource> 
       <calloutGraphics>true</calloutGraphics> 
       <!-- DEFAULT HTML CONFIG --> 
       <targetDirectory>${project.build.directory}/site</targetDirectory> 
       <htmlCustomization>src/site/docbook-config/docbook-html.xsl</htmlCustomization> 
       <htmlStylesheet>css/apache-maven-fluido-1.3.0.min.css</htmlStylesheet> 
       <!-- // DEFAULT HTML CONFIG --> 
      </configuration> 
     </plugin> 

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

Надеется, что это помогает

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