Sphinx 常見問題

這是有關 Sphinx 的常見問題列表。歡迎隨時建議新的條目！

如何…

… 在沒有 LaTeX 的情況下建立 PDF 檔案？

rinohtype 提供了一個 PDF 建置器，可以作為 LaTeX 建置器的直接替代品。

… 取得章節編號？

它們在 LaTeX 輸出中是自動的；對於 HTML，請在您想要開始編號的 toctree 指令中給定 :numbered: 選項。

… 客製化已建置 HTML 檔案的外觀？

使用主題，請參閱HTML 主題設定。

… 新增全域替換或包含？

將它們新增到 rst_prolog 或 rst_epilog 設定值中。

… 在側邊欄中顯示完整的 TOC 樹狀結構？

在自訂版面配置範本中使用 toctree 可呼叫物件，可能在 sidebartoc 區塊中。

… 編寫我自己的擴充套件？

請參閱教學課程。

… 從我現有的 MoinMoin 標記文件轉換？

最簡單的方法是轉換為 xhtml，然後轉換 xhtml 到 reStructuredText。您仍然需要標記類別等，但標題和程式碼範例會乾淨地通過。

如需更多擴充套件和其他貢獻內容，請參閱 sphinx-contrib 儲存庫。

Sphinx 與…搭配使用

Read the Docs

Read the Docs 是一個基於 Sphinx 的文件託管服務。他們將託管 Sphinx 文件，並支援許多其他功能，包括版本支援、PDF 產生等等。入門指南 是開始的好地方。

Epydoc

有一個第三方擴充套件提供 api 角色，該角色引用給定識別碼的 Epydoc API 文件。

Doxygen

Michael Jones 開發了一個 reStructuredText/Sphinx 橋樑到 doxygen，稱為 breathe。

SCons

Glenn Hutchings 編寫了一個 SCons 建置腳本來建置 Sphinx 文件；它託管在這裡：https://bitbucket-archive.softwareheritage.org/projects/zo/zondo/sphinx-scons.html

PyPI

Jannis Leidel 編寫了一個 setuptools 命令，可以自動將 Sphinx 文件上傳到 PyPI 封裝文件區域 https://pythonhosted.org/。

GitHub Pages

請將 sphinx.ext.githubpages 新增到您的專案中。它允許您在 GitHub Pages 中發布您的文件。它會在自動建置 HTML 文件時，為 GitHub Pages 產生輔助檔案。

MediaWiki

請參閱 sphinx-wiki，這是 Kevin Dunn 的專案。

Google Analytics

您可以使用自訂的 layout.html 範本，像這樣

{% extends "!layout.html" %}

{%- block extrahead %}
{{ super() }}
<script>
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'XXX account number XXX']);
  _gaq.push(['_trackPageview']);
</script>
{% endblock %}

{% block footer %}
{{ super() }}
<div class="footer">This page uses <a href="https://analytics.google.com/">
Google Analytics</a> to collect statistics. You can disable it by blocking
the JavaScript coming from www.google-analytics.com.
<script>
  (function() {
    var ga = document.createElement('script');
    ga.src = ('https:' == document.location.protocol ?
              'https://ssl' : 'https://www') + '.google-analytics.com/ga.js';
    ga.setAttribute('async', 'true');
    document.documentElement.firstChild.appendChild(ga);
  })();
</script>
</div>
{% endblock %}
Google 搜尋

若要使用 Google 搜尋取代 Sphinx 的內建搜尋功能，請按照以下步驟操作

  1. 前往 https://cse.google.com/cse/all 建立 Google 搜尋程式碼片段。

  2. 複製程式碼片段並將其貼到 Sphinx 專案中的 _templates/searchbox.html

    <div>
   <h3>{{ _('Quick search') }}</h3>
   <script>
      (function() {
         var cx = '......';
         var gcse = document.createElement('script');
         gcse.async = true;
         gcse.src = 'https://cse.google.com/cse.js?cx=' + cx;
         var s = document.getElementsByTagName('script')[0];
         s.parentNode.insertBefore(gcse, s);
      })();
   </script>
  <gcse:search></gcse:search>
</div>

  3. 將 searchbox.html 新增到 html_sidebars 設定值。

Sphinx vs. Docutils

總之：docutils 將 reStructuredText 轉換為多種輸出格式。Sphinx 以 docutils 為基礎，允許建構交叉引用和索引的文件主體。

docutils 是一個文字處理系統，用於將純文字文件轉換為其他更豐富的格式。如 docutils 文件 中所述，docutils 使用 readers 讀取文件，使用 parsers 將純文字格式解析為由不同類型的 nodes 組成的內部樹狀結構表示，並使用 writers 以各種文件格式輸出此樹狀結構。docutils 為一種純文字格式提供了解析器 - reStructuredText - 儘管已經實作了其他 樹狀結構外部 的解析器，包括 Sphinx 的 Markdown 解析器。另一方面，它為許多不同的格式提供了寫入器，包括 HTML、LaTeX、man pages、Open Document Format 和 XML。

docutils 通過各種 前端工具 公開其所有功能，例如 rst2html、rst2odt 和 rst2xml。但至關重要的是，所有這些工具以及 docutils 本身都與個別文件有關。它們不支援諸如交叉引用、文件索引或文件層次結構（通常體現在目錄中）的建構等概念。

Sphinx 以 docutils 為基礎，利用 docutils 的 readers 和 parsers，並提供自己的 建置器。因此，Sphinx 包裝了 docutils 提供的一些 writers。這使 Sphinx 能夠提供許多僅使用 docutils 無法實現的功能，例如上面概述的那些功能。

Epub 資訊

以下列表提供了一些關於建立 epub 檔案的提示

  • 將文字分割成多個檔案。個別 HTML 檔案越長，電子書閱讀器渲染它們所需的時間就越長。在極端情況下，渲染可能需要長達一分鐘。

  • 嘗試盡量減少標記。這也有助於縮短渲染時間。

  • 對於某些閱讀器，您可以使用 CSS @font-face 指令來使用嵌入式或外部字型。這對於程式碼列表非常有用，程式碼列表通常在右邊界被截斷。預設的 Courier 字型（或變體）相當寬，您在一行上最多只能顯示 60 個字元。如果您將其替換為較窄的字型，您可以在一行上獲得更多字元。您甚至可以使用 FontForge 並建立一些免費字型的窄變體。在我的情況下，我一行最多可以顯示 70 個字元。

    您可能需要稍微實驗一下，直到獲得合理的結果。

  • 測試建立的 epubs。您可以使用多種替代方案。我所知道的有 Epubcheck、Calibre、FBreader（雖然它不渲染 CSS）和 Bookworm。對於 Bookworm，您可以從 https://code.google.com/archive/p/threepress 下載原始碼並執行您自己的本地伺服器。

  • 大型浮動 div 無法正確顯示。如果它們覆蓋多個頁面，則 div 僅顯示在第一頁上。在這種情況下，您可以從 sphinx/themes/epub/static/ 目錄將 epub.css 複製到您的本地 _static/ 目錄，並移除浮動設定。

  • 在 toctree 指令之外插入的檔案必須手動包含。這有時適用於附錄，例如詞彙表或索引。您可以使用 epub_post_files 選項新增它們。

  • epub 封面頁的處理方式與 reStructuredText 程序不同，後者會自動解析圖像路徑並將圖像放入 _images 目錄。對於 epub 封面頁，請將圖像放入 html_static_path 目錄中，並在 epub_cover 設定選項中使用其完整路徑引用它。

  • kindlegen 命令可以將 epub3 結果檔案轉換為 Kindle 的 .mobi 檔案。在執行以下命令後，您可以在 _build/epub 下取得 yourdoc.mobi

    $ make epub
$ kindlegen _build/epub/yourdoc.epub

    kindlegen 命令不接受標題環繞 toctree 指令的文件

    Section Title
=============

.. toctree::

   subdocument

Section After Toc Tree
======================

    kindlegen 假設所有文件都按順序排列，但結果文件對於 kindlegen 來說具有複雜的順序

    ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``

    如果您收到以下錯誤，請修正您的文件結構

    Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
Error(prcgen):E24001: The table of content could not be built.

Texinfo 資訊

有兩個主要的程式用於閱讀 Info 檔案，info 和 GNU Emacs。info 程式功能較少，但在大多數 Unix 環境中都可用，並且可以從終端機快速存取。Emacs 提供更好的字型和顏色顯示，並支援廣泛的自訂（當然）。

注意事項

如果您想要建立 Texinfo 檔案，以下注意事項可能會有所幫助

  • 每個章節對應於 Info 檔案中的不同 node。

  • 冒號 (:) 無法在選單條目和 xrefs 中正確跳脫。它們將被替換為分號 (;)。

  • 可以使用有點官方的 URI 方案 info 建立指向外部 Info 檔案的連結。例如

    info:Texinfo#makeinfo_options