使用 Maven 维护用户文档

Question

Closed. This question is seeking recommendations for software libraries, tutorials, tools, books, or other off-site resources. It does not meet Stack Overflow guidelines. It is not currently accepting answers.

---

我们不允许提出寻求软件库、教程、工具、书籍或其他场外资源推荐的问题。您可以编辑问题，以便用事实和引文来回答。

6 年前已关闭。

Answer 1

我假设您还没有看过 Maven 站点文档生成但使用 maven-site-plugin。它非常强大，允许您合并并包含 JavaDoc 生成以及 OpenOffice 文档中的内容。

虽然站点文档不会输出为 PDF，但它会输出为静态 HTML 网站，该网站具有许多内置功能。使用 Maven 配置文件，您可以配置 Maven 生成一个供内部使用的站点，其中包括 Surefire 测试结果和其他检查报告，如 Checkstykle 和 PMD。在另一个配置文件中，您可以将其配置为仅生成分发给客户所需的文档，其中不包括客户可能不关心的内部报告。

但需要注意的是，Maven 3 的大部分站点文档生成都发生了变化。虽然 Maven 3 的大部分向后兼容 Maven 2，但请注意 Maven 3 的报告更改。查看以下链接：

• 站点生成兼容性
• 将 maven-site-plugin 转换为
  Maven 3

Answer 2

如果带有外部文档的站点插件无法产生足够高的质量，您可以使用带有 Maven 的 docbook 来生成 HTML 和 PDF 输出。事实上，Sonatype 对他们的所有书籍（例如 Maven：完整参考、Nexus 书籍、M2Eclipse 书籍...）都是这样做的，并且它们是开源的，因此您可以看到它是如何工作的，并复制设置并根据您的需要进行修改。使用 docbook 的优点是工具非常好（例如 xmlmind），并且它可以生成带有索引、目录等的印刷质量书籍。

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

Answer 3

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

阅读此说明，了解如何添加转换后的 DocBook to HTML 复制到 Maven 项目站点。

有趣的相关问题：

• 用于格式化 XML DocBook 的推荐工具链是什么？。

Answer 4

我有一个多模块 Maven 项目，其中每个模块都有自己的以文档格式编写的参考手册。然后我有一个通用参考手册，也是用文档书编写的，其中包括其他内容，因此我正在重复使用该文档。
当我执行 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>

您可以在此处查看我的项目站点，甚至可以将源代码下载到您的计算机中看看整个事情是如何设置的。
如果您有任何疑问，请随时与我们联系。

希望它有帮助

干杯
卡洛斯