Maven 站点文档：添加指向其他文档的链接答案

【问题标题】：Maven site documentation: Add links to additional documentsMaven 站点文档：添加指向其他文档的链接
【发布时间】：2015-03-04 06:52:00
【问题描述】：

我想使用 Maven 站点插件生成项目文档。 “项目信息”和“项目报告”的默认布局、结构和功能对我来说是可以的。但是我想添加一个额外的（第三个）部分“附加文档”，如果项目中有这样的文档，它会链接到更多的文档。

我可以创建一个目录src/site/resources/otherDocu，文件将根据需要复制到target/site/otherDocu 目录。但是，生成的站点不会链接到它们。

我想要第三部分“附加文档”，其中列出并链接了上述目录中的文件。我想用尽可能小的开销来做到这一点。具体来说，如果可以避免，我不想包含自己的site.xml，以及许多解决方案中描述的 css 等。如何使用默认站点配置并仅“注入”一部分？或者，如果这是唯一的方法，则应该可以在父 POM 中仅配置一次文件（例如 site.xml）并为所有其他项目继承它。如何让它列出在src/site/resources/otherDocu 中找到的文件并显示指向它们的链接？

或者，我也在考虑：我可以编写一个自己的报告插件，它可以做到这一点，然后我只需要在 POM 的“报告/插件”部分中指定这个插件，就像我为其他报告插件。使用此解决方案，我可能可以在“项目报告”部分创建一个附加条目，就像其他所有报告插件一样，这是朝着正确方向迈出的一步。但是我需要几个条目（因为有几个链接的文档），或者一个带有子条目的条目“附加文档”。

哪条路更容易走？您有推荐或类似的解决方案吗？有没有人有一个文件（site.xml 或类似文件）已经列出了一些，不需要所有其他资源（图像等）并且可以继承？

【问题讨论】：

标签： maven maven-site-plugin parent-pom

【解决方案1】：

保持默认行为的第一件事是使用something in your site descriptor:

  <body>
     <menu ref="reports"/>
     <menu ref="modules"/>
  </body>

你用来自动将文件复制到目标的东西是resources as you can read in the docs。

此外，您还需要通过报告插件来自动创建文档。

【讨论】：

非常感谢！我听从了你的建议，结果发现，通过编写我自己的报告插件，我什至不需要自己的站点描述符，但可以使用默认的（不需要我自己的 site.xml）。我的报告的输出被添加到标准报告列表中（由<menu ref="reports"/> 生成的列表）。
顺便说一句，我发现最有用的链接：Codehaus: write report plugin，Sonatype: write plugin。 4thline.org: about outputDirectory etc、maven: Plugin configuration、maven: Java5 Annotations

【解决方案2】：

这就是我所做的..相对简单：

src/site/site.xml:

<?xml version="1.0" encoding="ISO-8859-1"?>
<project name="${project.name}">
    <body>
        <menu name="Menu Title">
            <item name="Documentation" href="docs.html"/>
        </menu>
    </body>
</project>

上面创建了一个到 docs.html 页面的链接。然后使用 apt（或其他可能的语言）创建文档页面

src/site/apt/docs.apt：

    -------------
    Documentation
    -------------

Documentation

    Some text {{{/path/to/doc}document}}.

如果您不想创建单独的页面，您可以只在 site.xml 中插入指向文档的链接。

【讨论】：

谢谢，但不是我想要的，原因有两个：首先，拥有自己的 site.xml 会删除所有默认行为（指向项目信息和项目报告的链接），我必须重建/包含“手动”到我自己的 site.xml 中（除非这可以通过一些非常短的代码来完成 - 可以吗？）。其次，该解决方案应该在“otherDocumentation”目录中收集文件，而无需我一一列出。我想要一个适用于所有项目的通用解决方案，即自动收集现有项目文档的相同文档配置文件，这些文档可能因项目而异。
首先，拥有自己的 site.xml 会删除所有默认行为 ... -- 我展示的示例只是向默认站点页面添加了一个菜单部分，它没有替换整个页面。 其次，解决方案应该收集“otherDocumentation”目录中的文件，我不必一一列出。 -- 在我自己的项目中，我使用xhtml和javascript生成动态内容。虽然这可能不符合您的需求，但它确实表明动态内容是可能的。
我展示的示例只是在默认站点页面中添加了一个菜单部分，它不会替换整个页面。 -- 希望是这样...当然，默认页面布局和 CSS 等仍然存在，如果你的意思是这样的话。但是当我使用您列出的 site.xml 时，所有其他菜单项都消失了，而 site.xml 中定义的一项是唯一剩下的一项。我可以使用<menu ref="reports"/><menu ref="modules"/> 再次添加默认菜单项，但想避免这种情况。按照@khmarbaise 的建议，通过编写自己的报告插件找到了更适合我的解决方案。