範本

Sphinx 使用 Jinja 範本引擎來處理其 HTML 範本。Jinja 是一個以文字為基礎的引擎，靈感來自 Django 範本，因此任何使用過 Django 的人都會對它感到熟悉。它也為那些需要熟悉它的人提供了優秀的文件。

我需要使用 Sphinx 的範本來產生 HTML 嗎？

不需要。您有其他幾個選項

Jinja/Sphinx 範本入門

Sphinx 中的預設範本語言是 Jinja。它受到 Django/Smarty 的啟發，並且易於理解。Jinja 中最重要的概念是範本繼承，這表示您可以僅覆寫範本內的特定區塊，在自訂它的同時，也將變更保持在最低限度。

若要自訂文件輸出，您可以覆寫所有範本（包括版面配置範本和子範本），方法是將與原始檔名相同名稱的檔案新增到 Sphinx 快速入門為您產生的結構的範本目錄中。

Sphinx 將首先在 templates_path 的資料夾中尋找範本，如果在那裡找不到它正在尋找的範本，它會退回到所選主題的範本。

範本包含變數，在評估範本時會替換為值、標籤，用於控制範本的邏輯，以及用於範本繼承的 區塊。

Sphinx 的 基本 主題提供了基本範本，其中包含幾個它將用資料填滿的區塊。這些區塊位於 Sphinx 安裝目錄的 themes/basic 子目錄中，並由所有內建的 Sphinx 主題使用。在 templates_path 中具有相同名稱的範本會覆寫所選主題提供的範本。

例如，若要將新的連結新增到包含相關連結的範本區域，您只需新增一個名為 layout.html 的新範本，其內容如下

{% extends "!layout.html" %}
{% block rootrellink %}
    <li><a href="https://project.invalid/">Project Homepage</a> &raquo;</li>
    {{ super() }}
{% endblock %}

透過在覆寫的範本名稱前加上驚嘆號，Sphinx 將從底層的 HTML 主題載入版面配置範本。

重要

如果您覆寫了一個區塊，請在某處呼叫 {{ super() }} 以呈現擴展範本中區塊的原始內容 – 除非您不希望該內容顯示出來。

使用內建範本

內建的 基本 主題提供了所有內建 Sphinx 主題所基於的範本。它具有以下您可以覆寫或使用的元素

區塊（Blocks）

layout.html 範本中存在以下區塊

doctype

輸出格式的 doctype。預設情況下，這是 XHTML 1.0 Transitional，因為這是最接近 Sphinx 和 Docutils 產生的格式，除非您想切換到 HTML 5 或不同的但相容的 XHTML doctype，否則最好不要變更它。

linktags

此區塊會將一對 <link> 標籤新增到範本的 head 區段。

extrahead

此區塊預設為空白，可用於將額外內容新增到產生的 HTML 檔案的 <head> 標籤中。這是新增 JavaScript 或額外 CSS 檔案參考的正確位置。

relbar1、relbar2

此區塊包含關聯列，即相關連結的清單（左側的父文件，以及右側的索引、模組等的連結）。relbar1 出現在文件之前，relbar2 出現在文件之後。預設情況下，兩個區塊都會填滿；若要僅在文件之前顯示關聯列，您可以像這樣覆寫 relbar2

{% block relbar2 %}{% endblock %}
rootrellink、relbaritems

在關聯列內有三個區段：rootrellink、文件中的連結和自訂的 relbaritems。rootrellink 是一個區塊，預設情況下包含指向根文件的清單項目，relbaritems 是一個空白區塊。如果您覆寫它們以將額外連結新增到列中，請確保它們是清單項目，並以 reldelim1 結尾。

document

文件本身的內容。它包含「body」區塊，個別內容由子範本（例如 page.html）放入其中。

注意

為了使內建的 JavaScript 搜尋在結果頁面上顯示頁面預覽，文件或主體內容應包裝在包含 role="main" 屬性的 HTML 元素中。例如

<div role="main">
  {% block document %}{% endblock %}
</div>
sidebar1、sidebar2

側邊欄的可能位置。sidebar1 出現在文件之前，預設為空白，sidebar2 出現在文件之後，並包含預設側邊欄。如果您想交換側邊欄位置，請覆寫此項並呼叫 sidebar 輔助函式

{% block sidebar1 %}{{ sidebar() }}{% endblock %}
{% block sidebar2 %}{% endblock %}

（例如，sphinxdoc.css 樣式表需要側邊欄的 sidebar2 位置。）

sidebarlogo

側邊欄內的標誌位置。如果您想在側邊欄頂端放置一些內容，請覆寫此項。

footer

頁尾 div 的區塊。如果您想要自訂頁尾或在其之前或之後的標記，請覆寫此項。

以下四個區塊僅用於未在 html_sidebars 組態值中指派自訂側邊欄清單的頁面。它們的使用已被棄用，取而代之的是單獨的側邊欄範本，這些範本可以透過 html_sidebars 包含。

sidebartoc

側邊欄內的目錄。

版本 1.0 中已棄用。

sidebarrel

側邊欄內的關聯連結（上一篇、下一篇文件）。

版本 1.0 中已棄用。

sidebarsourcelink

側邊欄內的「顯示原始碼」連結（通常僅在 html_show_sourcelink 啟用時顯示）。

版本 1.0 中已棄用。

sidebarsearch

側邊欄內的搜尋框。如果您想在側邊欄底部放置一些內容，請覆寫此項。

版本 1.0 中已棄用。

組態變數

在範本內，您可以使用 {% set %} 標籤設定版面配置範本使用的一些變數

reldelim1

關聯列左側項目的分隔符號。預設值為 ' &raquo;'。關聯列中的每個項目都以這個變數的值結尾。

reldelim2

關聯列右側項目的分隔符號。預設值為 ' |'。關聯列中除了最後一個項目之外，每個項目都以這個變數的值結尾。

覆寫方式如下

{% extends "!layout.html" %}
{% set reldelim1 = ' &gt;' %}
script_files

在此處新增額外的腳本檔案，如下所示

{% set script_files = script_files + ["_static/myscript.js"] %}

版本 1.8.0 中已棄用: 請改用 .Sphinx.add_js_file()。

輔助函式

Sphinx 在範本中提供了各種 Jinja 函式作為輔助工具。您可以使用它們來產生連結或輸出多次使用的元素。

pathto(document)

傳回 Sphinx 文件的路徑，作為 URL。使用它來參考已建立的文件。

pathto(file, 1)

傳回檔案的路徑，該檔案是相對於產生輸出根目錄的檔案名稱。使用它來參考靜態檔案。

hasdoc(document)

檢查是否有名為 document 的文件存在。

傳回已呈現的側邊欄。

relbar()

傳回已呈現的關聯列。

warning(message)

發出警告訊息。

全域變數

這些全域變數在每個範本中都可用，並且可以安全使用。還有更多變數，但它們大多數是實作細節，並且未來可能會變更。

builder

產生器的名稱（例如 html 或 htmlhelp）。

copyright 的值。

docstitle

文件的標題（html_title 的值），除非使用「單一檔案」產生器，否則會設定為 None。

embedded

如果建置的 HTML 旨在嵌入到處理導覽的某些檢視應用程式中，而不是網頁瀏覽器中（例如 HTML 說明或 Qt 說明格式），則為 True。在這種情況下，不包含側邊欄。

favicon_url

從目前文件到 HTML favicon 影像的相對路徑，或 favicon 的 URL，或 ''。

版本 4.0 中新增。

file_suffix

產生器的 out_suffix 屬性的值，即輸出檔案將取得的副檔名。對於標準 HTML 產生器，這通常是 .html。

has_source

如果複製 reStructuredText 文件來源（如果 html_copy_source 為 True），則為 True。

language

language 的值。

last_updated

建置日期。

logo_url

從目前文件到 HTML 標誌影像的相對路徑，或標誌的 URL，或 ''。

版本 4.0 中新增。

master_doc
root_doc

master_doc 或 root_doc（別名）的值，用於 pathto()。

版本 4.0 中新增: root_doc 範本變數。

pagename

目前檔案的「頁面名稱」，即如果檔案是從 reStructuredText 來源產生的文件名稱，或相對於輸出目錄的等效階層式名稱 ([目錄/]不含副檔名的檔案名稱)。

project

project 的值。

release

release 的值。

要放在關聯列左側，「下一篇」和「上一篇」旁邊的連結清單。這通常包含一般索引和其他索引的連結，例如 Python 模組索引。如果您自己新增內容，則它必須是元組 (pagename, 連結標題, 存取鍵, 連結文字)。

shorttitle

html_short_title 的值。

show_source

如果 html_show_sourcelink 為 True，則為 True。

sphinx_version

用於建置的 Sphinx 版本，表示為字串，例如「3.5.1」。

sphinx_version_tuple

用於建置的 Sphinx 版本，表示為五個元素的元組。對於 Sphinx 版本 3.5.1 beta 3，這將是 (3, 5, 1, 'beta', 3)。第四個元素可以是以下其中之一：alpha、beta、rc、final。final 的最後一個元素始終為 0。

版本 4.2 中新增。

docutils_version_info

用於建置的 Docutils 版本，表示為五個元素的元組。對於 Docutils 版本 0.16.1 beta 2，這將是 (0, 16, 1, 'beta', 2)。第四個元素可以是以下其中之一：alpha、beta、candidate、final。final 的最後一個元素始終為 0。

版本 5.0.2 中新增。

styles

主要樣式表的名稱清單，由主題或 html_style 給定。

版本 5.1 中新增。

title

目前文件的標題，如 <title> 標籤中所使用。

use_opensearch

html_use_opensearch 的值。

version

version 的值。

除了這些值之外，還有所有可用的主題選項（以 theme_ 為前綴），以及使用者在 html_context 中給定的值。

在從來源檔案建立的文件中（與自動產生的檔案（如模組索引，或已經是 HTML 格式的文件）相反），這些變數也可用

body

包含 HTML 產生器產生的頁面內容（HTML 格式）的字串，在套用主題之前。

display_toc

如果目錄包含多個條目，則為 True 的布林值。

meta

文件元資料（字典），請參閱 檔案範圍元資料。

metatags

包含頁面的 HTML meta 標籤的字串。

next

導覽的下一篇文件。此變數為 false 或具有兩個屬性 link 和 title。標題包含 HTML 標記。例如，若要產生下一頁的連結，您可以使用以下程式碼片段

{% if next %}
<a href="{{ next.link|e }}">{{ next.title }}</a>
{% endif %}
page_source_suffix

已呈現檔案的副檔名。由於我們支援 source_suffix 的清單，這將允許您正確連結到原始來源檔案。

parents

導覽的父文件清單，結構類似於 next 項目。

prev

與 next 類似，但用於上一頁。

sourcename

目前文件複製的來源檔案名稱。僅當 html_copy_source 值為 True 時，此值才為非空值。在建立自動產生的檔案時，此值為空值。

toc

目前頁面的本機目錄，以 HTML 項目符號清單呈現。

toctree

產生包含目前頁面的全域 TOC 樹狀結構的可呼叫物件，以 HTML 項目符號清單呈現。選用關鍵字引數

collapse

如果為 true，則所有不是目前頁面祖先的 TOC 條目都會摺疊。預設為 True。

maxdepth

樹狀結構的最大深度。將其設定為 -1 以允許無限深度。預設為 toctree 指令中選取的最大深度。

titles_only

如果為 true，則僅將最上層文件標題放在樹狀結構中。預設為 False。

includehidden

如果為 true，則 ToC 樹狀結構也將包含隱藏的條目。預設為 False。