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的报告更改。查看以下链接：

Answer 2

如果带有外部文档的网站插件产生的质量不够高，您可以使用带有Maven的docbook来生成HTML和PDF输出。事实上，Sonatype为他们所有的书（例如Maven：The Complete Reference，Nexus book，M2Eclipse book ...）做了这些，并且它们是开源的，所以你可以看到它是如何工作的，并复制设置并根据你的需要进行修改。使用docbook的好处是工具非常好（例如xmlmind），并且它生成带有index，toc等的打印质量书。

哦，既然你提到它，还有一个Maven的LaTeX插件，但我没有使用它的经验（但在我的Maven使用之前使用LaTeX很多......）

Answer 3

另一个解决方案是Maven docbkx插件，用于将DocBook转换为PDF; HTML等

如果您希望看到您的DocBook内容也出现在Maven生成的网站中，请阅读此说明，了解如何将已转换的DocBook to HTML添加到Maven项目网站。

有趣的相关问题：

What is the recommended tool chain for formatting XML DocBook?。

Answer 4

我有一个多模块maven项目，其中每个模块都有自己的以docbook格式编写的参考手册。然后我有一个通用的参考手册，也写在docbook中，包括其他的，所以我重新使用文档。当我执行mvn site时，该项目会生成包含所有参考手册的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维护用户文档

4 个答案: