Mavenを使用してユーザー文書を管理する

Question

Mavenを使用してJavaサーバースタイルのアプリケーションを構築しています。これは、顧客が必要とする機能を備えた最終製品（本質的に.jar）を生成するために相互に接続することができるいくつかのモジュール（単一のMaven「リアクタ」内）から構成されています。すべての内部はJavaDocとすべてを使用して文書化されていますが、それは顧客にどのように動作させるかを知るために与えることができないものです。現在、私たちは、エンドユーザのドキュメントとして機能するOpenOfficeドキュメントを持っています。

私は、このドキュメントをモジュールのソースと一緒に（手作業で）各モジュールのドキュメントが維持されるMavenビルドプロセスに統合したいと思います。最終的なドキュメントは、必要なモジュールドキュメントセクションを参照して、可能であれば、JavaDocsを参照することができます。最終的には、文書をPDFとして出力する必要があります。

Mavenプラグインに何か経験がありますか？ DocBookは正しいツールですか？多分ラテックス？それとも全く違う何か？ 「OpenOfficeといくつかのテキストブロックを貼り付ける」という音声も答えになる可能性があります。

Answer 1

私はMaven site documentation generationをまだ見ておらず、maven-site-pluginとしています。これは非常に堅牢で、JavaDocの生成とOpenOfficeドキュメントのコンテンツを組み込んでインクルードすることができます。

サイトのドキュメントはPDFとして出力されませんが、多くの機能を内蔵した静的なHTML Webサイトとして出力されます。Mavenプロファイルを使用すると、Mavenを使用して、 CheckstykleとPMDのようなチェックのための確かなテスト結果と他のレポート。別のプロファイルでは、クライアントが気にしない内部レポートを含まないクライアントへの配布に必要なドキュメントのみを生成するように構成できます。

つのノートのMaven 3のほとんどが、Mavenの2との後方互換性がありますが、しかし、サイトのドキュメントの多くの世代は、Mavenの3のために変更され、これらのリンクをチェックアウト3. Mavenのためのレポーティング変化に留意：

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

Answer 2

とケースに外部ドキュメントを持つサイトのプラグインが十分に高い品質を生成しない、あなたは、HTMLやPDF出力を生成するためのMavenでのDocBookを使用することができます。実際、Sonatypeはすべての書籍（例：Maven：The Complete Reference、Nexus book、M2Eclipse book ...）でこれを行います。オープンソースなので、すべての仕組みを確認して設定をコピーし、必要に応じて変更できます。ドックブックを使う利点は、ツーリングがかなり良い（例えばxmlmind）、インデックス、tocなどで印刷品質の本を作ることです。

ああ、あなたはそれを言及したので、そこにMavenのためのLaTeXのプラグインもあるが、私はそれとまったく経験がありません（私の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

私は、各モジュールが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をチェックアウトすることができますし、さらにコンピュータにソースをダウンロードし、全部が設定されているかを見ることができます。 ご不明な点がございましたら、お気軽にお問い合わせください。

は、それは私が最終的にリポジトリを設定し、Mavenのサイトの世代でプレーした

乾杯 カルロス