使用 doxygen 生成具有自定义结构的 PDF

Question

在详细介绍之前，先简短介绍一下：

我正在尝试自定义 doxygen 生成的 pdf 文档结构。我已经在为 html 和 chm 输出执行此操作，但对于 pdf 它不起作用。
我的主要问题是，这是设计限制还是我遗漏了什么？
如果这是设计使然，我还有其他方法可以从 doxygen 开始，从而生成自定义的 pdf 文档吗？

详情如下：

我们正在使用 doxygen 为 C API 生成源代码文档，该 API 也使用 C++、C# 和 Java 封装。
我们希望将所有这些语言记录在一个文档中，但要按语言对其进行结构化。为了实现这一点，我们通过以下方式使用 DoxygenLayout.xml 文件自定义了文档结构：

• 首先是几页描述性文字，适用于所有 语言，我们称这部分为“用户手册”。
• 其次是 API 文档，它按不同的语言组织。

换句话说，我们完全禁用标准结构并定义我们自己的结构。 布局定义看起来很像这个简化的例子：

  <navindex>
    <tab type="mainpage" visible="yes" title="My Project"/>
    <tab type="pages" visible="no" title="" intro=""/>
    <tab type="modules" visible="no" title="" intro=""/>
    <tab type="namespaces" visible="no" title="">
      <tab type="namespacelist" visible="no" title="" intro=""/>
      <tab type="namespacemembers" visible="no" title="" intro=""/>
    </tab>
    <tab type="classes" visible="no" title="">
      <tab type="classlist" visible="no" title="" intro=""/>
      <tab type="classindex" visible="no" title=""/> 
      <tab type="hierarchy" visible="no" title="" intro=""/>
      <tab type="classmembers" visible="no" title="" intro=""/>
    </tab>
    <tab type="files" visible="no" title="">
      <tab type="filelist" visible="no" title="" intro=""/>
      <tab type="globals" visible="no" title="" intro=""/>
    </tab>
    <tab type="examples" visible="no" title="" intro=""/>  

    <tab type="usergroup" title="User Manual">
        <tab type="user" title="Page 1" url="@ref page1"/>
    </tab>

    <tab type="usergroup" title="API documentation">
        <tab type="usergoup" title="C">
            <tab type="user" title="SomeFunction" url="@ref SomeFunction" />
            <tab type="user" title="AnotherFunction" url="@ref AnotherFunction" />
        </tab>
        <tab type="usergoup" title="C#">
            <tab type="usergroup" title="A.Class1">
                <tab type="user" title="SomeFunction" url="@ref A.Class1.SomeFunction" />
            </tab>
            <tab type="usergroup" title="B.Class2">
                <tab type="user" title="AnotherFunction" url="@ref B.Class2.AnotherFunction" />
            </tab>
        </tab>
        <tab type="usergoup" title="Java">
            <tab type="usergroup" title="com.xyz.A.Class1">
                <tab type="user" title="SomeFunction" url="@ref com.xyz.A.Class1.SomeFunction" />
            </tab>
            <tab type="usergroup" title="com.xyz.B.Class2">
                <tab type="user" title="AnotherFunction" url="@ref com.xyz.B.Class2.AnotherFunction" />
            </tab>
        </tab>
    </tab>
</navindex>

这对于 chm 和 html 输出非常有效，但不幸的是，对于可用于生成 pdf 的 latex 和 docbook 输出，它似乎完全被忽略了。 布局文件的文档暗示它应该独立于使用的输出工作：

# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed
# by doxygen. The layout file controls the global structure of the generated
# output files in an output format independent way. To create the layout file
# that represents doxygen's defaults, run doxygen with the -l option. You can
# optionally specify a file name after the option, if omitted DoxygenLayout.xml
# will be used as the name of the layout file.
#
# Note that if you run doxygen from a directory containing a file called
# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE
# tag is left empty.
LAYOUT_FILE            = "DoxygenLayout.xml"

Answer 1

Doxygen 在 latex 目录中生成了许多文件，在这种情况下最值得注意的是：

• refman.tex，有许多设置和不同章节的包含，可能最适合你想要的东西。
• doxygen.sty 带有 doxygen 使用的设置。可以修改这个文件（不是很建议），也可以通过配置标签 LATEX_EXTRA_STYLESHEET 添加额外的样式表，其中可以覆盖（例如通过更新命令）默认命令。

值得注意的还有 LATEX_HEADER、LATEX_FOOTER、EXTRA_PACKAGES 等设置，请参阅文档（http://www.doxygen.nl/manual/ 中的配置章节）了解这些和更多可能性。

对于 docbook 输出，当前版本 1.8.15 可能会更好一些，但 docbook 没有特殊的“样式表”。