自訂輸出

目錄

• 小調整
  • 整體色彩
  • 導覽
  • 動態內容
  • 頁首、頁尾和樣式表變更
• 變更頁面佈局
• 使用 XML 輸出

Doxygen 提供各種自訂層級。 小調整 章節討論如何對輸出結果的外觀和風格進行小幅調整。佈局 章節展示如何重新排序和隱藏頁面上的某些資訊。XML 輸出 章節展示如何基於 Doxygen 產生的 XML 輸出生成任何您想要的輸出。

小調整

接下來的小節將描述一些可以輕鬆調整的方面。

整體色彩

要更改 HTML 輸出的整體色彩，Doxygen 提供了三個選項

• HTML_COLORSTYLE_HUE
• HTML_COLORSTYLE_SAT
• HTML_COLORSTYLE_GAMMA

分別用於更改色彩的色調、飽和度和伽瑪校正。

為了您的方便，GUI 前端 Doxywizard 具有一個控制項，可讓您即時查看更改這些選項值對輸出的影響。

導覽

預設情況下，Doxygen 會顯示一個橫跨頁面全寬的標題區域，並在內容下方顯示導覽樹，作為每個 HTML 頁面左側的側邊欄。

這對應於 Doxyfile 中的以下設定

• DISABLE_INDEX = YES
• GENERATE_TREEVIEW = YES
• FULL_SIDEBAR = NO

您可以使用以下設定，使側邊欄跨越整個頁面的高度

• DISABLE_INDEX = YES
• GENERATE_TREEVIEW = YES
• FULL_SIDEBAR = YES

您也可以用每個 HTML 頁面頂部的索引標籤替換導覽樹，對應於以下設定

• DISABLE_INDEX = NO
• GENERATE_TREEVIEW = NO

甚至可以使用兩種形式的導覽

• DISABLE_INDEX = NO
• GENERATE_TREEVIEW = YES

如果您已經使用外部索引（即啟用以下選項之一：GENERATE_HTMLHELP、GENERATE_ECLIPSEHELP、GENERATE_QHP 或 GENERATE_DOCSET），那麼您也可以停用所有索引，如下所示

• DISABLE_INDEX = YES
• GENERATE_TREEVIEW = NO

動態內容

為了使 HTML 輸出更具互動性，Doxygen 提供了一些預設停用的選項

• 啟用 HTML_DYNAMIC_SECTIONS 會使 Doxygen 預設隱藏 HTML 中的某些內容（如圖表），並讓讀者根據需要展開這些部分。
• 啟用 HAVE_DOT 以及 INTERACTIVE_SVG，同時將 DOT_IMAGE_FORMAT 設定為 svg，將使 Doxygen 產生允許使用者縮放和平移的 SVG 影像（僅當影像大小超過一定大小時才會發生）。

頁首、頁尾和樣式表變更

要詳細調整字型、色彩、邊距或其他 HTML 輸出外觀和風格方面，您可以建立不同的 階層式樣式表。您也可以讓 Doxygen 對其產生的每個 HTML 頁面使用自訂的頁首和頁尾，例如使輸出符合您網站其餘部分使用的樣式。

為此，請先按如下方式執行 Doxygen

doxygen -w html header.html footer.html customdoxygen.css

這將建立 3 個檔案

• header.html 是一個 HTML 片段，Doxygen 通常用它來開始 HTML 頁面。請注意，該片段以 body 標籤結尾，並且包含一些 $word 形式的命令。這些將由 Doxygen 動態替換。
• footer.html 是一個 HTML 片段，Doxygen 通常用它來結束 HTML 頁面。這裡也可以使用特殊命令。此檔案包含指向 www.doxygen.org 的連結，以及 body 和 html 結束標籤。
• customdoxygen.css 是 Doxygen 使用的預設階層式樣式表。建議僅查看此檔案，並將您喜歡的一些設定放在單獨的樣式表中，並透過 HTML_EXTRA_STYLESHEET 參考這些額外的檔案來覆寫它們。

您應該編輯這些檔案，然後從設定檔中參考它們。

• HTML_HEADER = header.html
• HTML_FOOTER = footer.html
• HTML_EXTRA_STYLESHEET = my_customdoxygen.css

注意

不再建議使用 HTML_STYLESHEET，因為它會使升級到較新版本的 Doxygen 變得困難。請改用 HTML_EXTRA_STYLESHEET。

有關您可以在自訂頁首中使用的可能中繼命令的更多資訊，請參閱 HTML_HEADER 標籤的文件。

注意

您不應將樣式表放在 HTML 輸出目錄中。將其視為原始檔案。Doxygen 會為您複製它。

如果您在自訂頁首中使用影像或其他外部內容，則需要確保它們最終位於 HTML 輸出目錄中，例如透過編寫一個執行 Doxygen 的腳本，然後將影像複製到輸出。

警告

升級到較新版本的 Doxygen 後，頁首和頁尾的結構可能會變更，因此如果您使用自訂的頁首或頁尾，則升級後可能不再產生有效的輸出。

變更頁面佈局

在某些情況下，您可能希望變更輸出的結構方式。在這種情況下，不同的樣式表或自訂頁首和頁尾沒有幫助。

Doxygen 提供的解決方案是一個佈局檔案，您可以修改它，Doxygen 將使用它來控制呈現哪些資訊、以何種順序呈現，以及在一定程度上如何呈現資訊。佈局檔案是一個 XML 檔案。

可以使用以下命令由 Doxygen 產生預設佈局

doxygen -l

可以選擇指定佈局檔案的名稱，如果省略，將使用 DoxygenLayout.xml。

下一步是在設定檔中提及佈局檔案（另請參閱 LAYOUT_FILE）

LAYOUT_FILE = DoxygenLayout.xml

要變更佈局，您所需要做的就是編輯佈局檔案。

該檔案的頂級結構如下所示

<doxygenlayout version="1.0">
  <navindex>
    ...
  </navindex>
  <class>
    ...
  </class>
  <namespace>
    ...
  </namespace>
  <concept>
    ...
  </concept>
  <file>
    ...
  </file>
  <group>
    ...
  </group>
  <directory>
    ...
  </directory>
</doxygenlayout>

XML 檔案的根元素是 doxygenlayout，它有一個名為 version 的屬性，將來會使用它來處理不向後相容的變更。

由 navindex 元素識別的第一個部分表示顯示在每個 HTML 頁面頂部的導覽索引標籤的佈局。同時，如果啟用 GENERATE_TREEVIEW，它也會控制導覽樹中的項目。每個索引標籤由 XML 檔案中的 tab 元素表示。

您可以將 visible 屬性設定為 no 來隱藏索引標籤。您也可以透過將索引標籤的預設標題指定為 title 屬性的值來覆寫它。如果標題欄位是空字串（預設值），則 Doxygen 會填寫適當的語言特定標題。

您可以透過在 XML 檔案中移動 navindex 元素內的索引標籤元素，甚至變更樹狀結構來重新排序索引標籤。但是，請勿變更 type 屬性的值。僅支援一組固定的類型，每種類型都代表指向特定索引的連結。

您也可以使用名稱為「user」的類型新增自訂索引標籤。以下範例展示如何新增一個標題為「Google」的索引標籤，指向 www.google.com

  <navindex>
    ...
    <tab type="user" url="http://www.google.com" title="Google"/>
    ...
  </navindex>

url 欄位也可以是相對 URL。如果 URL 以 @ref 開頭，則該連結將指向已記錄的實體，例如類別、函式、群組或相關頁面。假設我們使用 @page 定義了一個標籤為 mypage 的頁面，那麼一個標籤為「我的頁面」且指向此頁面的索引標籤如下所示

  <navindex>
    ...
    <tab type="user" url="@ref mypage" title="My Page"/>
    ...
  </navindex>

您也可以使用類型為「usergroup」的索引標籤，將索引標籤分組到自訂群組中。以下範例將上述索引標籤放在一個標題為「我的群組」的使用者定義群組中

  <navindex>
    ...
    <tab type="usergroup" title="My Group">
      <tab type="user" url="http://www.google.com" title="Google"/>
      <tab type="user" url="@ref mypage" title="My Page"/>
    </tab>
    ...
  </navindex>

群組可以巢狀以形成階層。

預設情況下，導覽樹中的 usergroup 條目是連往群組內容的登陸頁面的連結。您可以使用 url 屬性連結到不同的頁面，就像您對 <tab> 元素所做的那樣，並使用 url="[none]" 來阻止任何連結，即

   <tab type="usergroup" title="Group without link" url="[none]">
   ...
   </tab>

navindex 之後的元素表示 Doxygen 產生的不同頁面的佈局

• class 元素表示為已記錄的類別、結構、聯合和介面產生的所有頁面的佈局。
• namespace 元素表示為已記錄的命名空間（以及 Java 套件）產生的所有頁面的佈局。
• concept 元素表示為已記錄的概念產生的所有頁面的佈局。
• file 元素表示為已記錄的檔案產生的所有頁面的佈局。
• group 元素表示為已記錄的群組（或主題）產生的所有頁面的佈局。
• directory 元素表示為已記錄的目錄產生的所有頁面的佈局。

在上述每個頁面元素中，每個 XML 元素都代表特定的資訊片段。有些片段可能出現在每一種頁面類型中，而其他片段則特定於某種頁面類型。Doxygen 將按照它們在 XML 檔案中出現的順序列出這些片段。

以下通用元素適用於每個頁面

briefdescription

代表頁面上的簡短描述。

detaileddescription

代表頁面上的詳細描述。

authorsection

代表頁面的作者章節（僅用於 man 手冊頁）。這是 man 手冊頁的單獨章節，其中包含類似以下的文字：由 Doxygen 自動為我的專案從原始碼產生。這不應與 Doxygen 命令 \author 或 \authors 混淆，後者會在詳細描述中產生一個作者段落。

以下通用元素適用於除了概念頁面之外的每個頁面

memberdecl

代表頁面上成員的快速概述（成員宣告）。此元素具有每個成員列表類型的子元素。文件中未詳細列出可能的子元素，但元素的名稱應該很好地指示元素代表的成員類型。

memberdef

代表頁面上的詳細成員列表（成員定義）。與 memberdecl 元素一樣，此元素也具有許多可能的子元素。

類別頁面具有以下特定元素

includes

代表獲取此類別定義所需的 include 檔案。

inheritancegraph

代表類別的繼承關係。請注意，CLASS_GRAPH 選項決定繼承關係是基底類別和衍生類別的列表還是圖形。

collaborationgraph

代表類別的協作圖。

allmemberslink

代表指向類別所有成員列表的連結。

usedfiles

代表從中提取類別文件之文件的列表。

概念頁面具有以下特定元素

includes

代表獲取此類別定義所需的 include 檔案。

definition

代表概念的定義

檔案頁面具有以下特定元素

includes

代表此檔案中包含的 #include 陳述式列表。

includegraph

代表檔案的 include 相依性圖。

includedbygraph

代表檔案的被 include 相依性圖。

sourcelink

代表指向此檔案原始碼的連結。

群組頁面具有特定的 groupgraph 元素，該元素表示顯示群組之間相依性的圖形。

類似地，目錄頁面具有特定的 directorygraph 元素，該元素表示根據目錄中檔案的 #include 關係顯示目錄之間相依性的圖形。

有些元素具有 visible 屬性，可透過將屬性的值設定為 "no" 來隱藏產生輸出中的片段。您也可以使用組態選項的值來決定可見性，方法是使用以錢字號開頭的名稱，例如。

  ...
  <includes visible="$SHOW_INCLUDE_FILES"/>
  ...

這主要是為了向後相容性而添加的。請注意，visible 屬性僅是 Doxygen 的提示。如果某個片段沒有相關資訊可用，即使將其設定為 yes，也會省略該片段（即不會產生空的區段）。
並非所有元素在佈局檔案中都顯示了 visible 屬性，但是無論如何都可以使用此屬性（預設為 visible="yes"）。

有些元素具有 title 屬性。此屬性可用於自訂 Doxygen 將用作片段標題的標題。

使用 XML 輸出

如果以上兩種方法仍然無法提供足夠的彈性，您也可以使用 Doxygen 產生的 XML 輸出作為基礎來產生您想要的輸出。為此，請將 GENERATE_XML 設定為 YES。

XML 輸出由名為 index.xml 的索引檔案組成，該檔案列出了 Doxygen 提取的所有項目，並參照了其他 XML 檔案以了解詳細資訊。索引的結構由綱要檔案 index.xsd 描述。所有其他 XML 檔案都由名為 compound.xsd 的綱要檔案描述。如果您喜歡一個大的 XML 檔案，可以使用 XSLT 檔案 combine.xslt 將索引和其他檔案組合在一起。

您可以使用任何 XML 解析器來解析這些檔案，也可以使用 Doxygen 來源發行版本的 addon/doxmlparser 目錄中找到的解析器。請查看 addon/doxmlparser/doxmlparser/index.py 和 addon/doxmlparser/doxmlparser/compound.py 以了解解析器的介面（它是由 generatedDS 產生的，並遵循 templates/xml 中找到的 XML 綱要檔案 index.xsd 和 compound.xsd）。請在 addon/doxmlparser/examples 中查看範例。

使用 doxmlparser 的優點是，它允許您僅將索引檔案讀入記憶體，然後僅讀取那些您透過導覽索引隱式載入的 XML 檔案。因此，即使對於非常大型的專案，將所有 XML 檔案作為一個大型 DOM 樹讀取也會超出記憶體容量，這仍然有效。

請參閱 Breathe 專案，以取得從 Python 使用 Doxygen XML 輸出，並將其與 Sphinx 文件產生器橋接的範例。

請前往下一個章節或返回索引。